LuaGameplay.wiki
author Wuzzy
Fri, 21 Jun 2019 23:23:16 +0100
changeset 1937 55255a1feba7
parent 1919 d9cd57b53b6e
child 1938 e1b83a39bbbc
permissions -rw-r--r--
LuaGameplay: Fix version of *MissionVar
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 =
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
     5
This page is a list of 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
     6
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
     7
<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
     8
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
     9
== `GameFlags` functions ==
1794
7b07726d12f3 LuaGameplay: LuaEvents
Wuzzy
parents: 1779
diff changeset
    10
`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
    11
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    12
=== <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
    13
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
    14
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    15
=== <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
    16
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
    17
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    18
=== <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
    19
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
    20
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    21
=== <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
    22
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
    23
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    24
== Turns ==
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    25
=== <tt>SkipTurn()</tt> (0.9.24) ===
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
    26
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
    27
1819
529bf5849f75 LuaGameplay: fix EndTurn call
Wuzzy
parents: 1818
diff changeset
    28
=== `EndTurn([noTaunts])` (0.9.23) ===
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
    29
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
    30
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
    31
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
    32
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    33
=== <tt>Retreat(time [, respectGetAwayTimeFactor)</tt> (0.9.25) ===
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
    34
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
    35
91756d20ce3e 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
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
    37
91756d20ce3e 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
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
    39
91756d20ce3e 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
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
    41
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    42
=== <tt>!SetTurnTimeLeft(newTurnTimeLeft)</tt> (0.9.25) ===
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
    43
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
    44
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    45
=== <tt>!SetReadyTimeLeft(newReadyTimeLeft)</tt> (0.9.25) ===
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
    46
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
    47
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    48
=== <tt>!SetTurnTimePaused(isPaused)</tt> (0.9.25) ===
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
    49
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
    50
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    51
=== <tt>!GetTurnTimePaused()</tt> (0.9.25) ===
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
    52
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
    53
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    54
=== <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
    55
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
    56
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    57
== Environment ==
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    58
=== <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
    59
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
    60
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
    61
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    62
=== <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
    63
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
    64
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    65
=== <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
    66
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
    67
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    68
=== <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
    69
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
    70
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    71
=== <tt>!GetWind()</tt> (0.9.24) ===
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
    72
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
    73
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    74
=== <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
    75
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
    76
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
    77
=== <tt>Explode(x, y, radius[, options])</tt> (0.9.24) ===
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
    78
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
    79
91756d20ce3e 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
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
    81
91756d20ce3e 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
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
    83
91756d20ce3e 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
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
    85
91756d20ce3e 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
`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
    87
91756d20ce3e 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
|| *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
    89
|| `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
    90
|| `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
    91
|| `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
    92
|| `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
    93
|| `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
    94
|| `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
    95
|| `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
    96
|| `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
    97
91756d20ce3e 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
`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
    99
91756d20ce3e 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
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
   101
<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
   102
-- 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
   103
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
   104
91756d20ce3e 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
-- 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
   106
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
   107
91756d20ce3e 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
-- 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
   109
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
   110
91756d20ce3e 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
-- 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
   112
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
   113
</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
   114
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   115
== Ammo ==
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   116
=== <tt>!SetAmmo(ammoType, count, probability, delay, numberInCrate)</tt> ===
1797
e8c8ffe6e22b LuaGameplay: for links to LuaEvents
Wuzzy
parents: 1796
diff changeset
   117
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
   118
91756d20ce3e 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
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
   120
91756d20ce3e 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
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
   122
91756d20ce3e 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
 * `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
   124
 * `count`: Initial ammo count. 9 = infinite
91756d20ce3e 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
 * `probability`: Crate probability. Max. value is 9. 0 = never
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
   126
 * `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
   127
 * `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
   128
91756d20ce3e 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
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
   130
91756d20ce3e 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
<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
   132
    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
   133
    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
   134
91756d20ce3e 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
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
   136
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   137
=== <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
   138
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
   139
91756d20ce3e 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
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
   141
91756d20ce3e 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
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
   143
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
   144
<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
   145
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   146
=== <tt>!SetAmmoDelay(ammoType, delay)</tt> ===
1907
806491e9ef60 LuaGameplay: Delay of 9999
Wuzzy
parents: 1906
diff changeset
   147
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
   148
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   149
=== <tt>!SetAmmoTexts(ammoType, name, caption, description [, showExtra])</tt> (0.9.23) ===
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
   150
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
   151
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
   152
 * `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
   153
 * `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
   154
 * `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
   155
 * `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
   156
 * `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
   157
91756d20ce3e 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
`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
   159
91756d20ce3e 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
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
   161
<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
   162
-- 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
   163
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
   164
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   165
=== <tt>!SetAmmoDescriptionAppendix(ammoType, descAppend)</tt> (0.9.23) ===
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
   166
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
   167
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
   168
91756d20ce3e 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
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
   170
91756d20ce3e 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
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
   172
<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
   173
-- 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
   174
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
   175
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   176
=== <tt>!AddAmmo(gearUid, ammoType, ammoCount)</tt> ===
1797
e8c8ffe6e22b LuaGameplay: for links to LuaEvents
Wuzzy
parents: 1796
diff changeset
   177
Adds `ammoType` to the specified gear. The amount added is determined by the arguments passed via `SetAmmo()` in the `onAmmoStoreInit()` [LuaEvents event handler]. `ammoCount` is an optional parameter. If this is set, the ammo will *not* be added, but instead set to `ammoCount`. A value of `0` will remove the weapon, a value of `AMMO_INFINITE` will give infinite ammo.
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
   178
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
   179
Note: By default, ammo is per-team, so calling `AddAmmo` for a hedgehog will give 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`.
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
   180
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   181
=== <tt>!GetAmmoName(ammoType [, ignoreOverwrite ])</tt> (0.9.23) ===
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
   182
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
   183
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   184
== Map ==
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   185
=== <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
   186
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
   187
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   188
=== <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
   189
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
   190
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   191
=== <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
   192
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
   193
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
   194
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
   195
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
   196
|| *`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
   197
|| 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
   198
|| 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
   199
|| 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
   200
|| 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
   201
|| 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
   202
|| 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
   203
|| 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
   204
|| 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
   205
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   206
=== <tt>!PlaceRubber(x, y, frameIdx)</tt> (0.9.23) ===
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
   207
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
   208
91756d20ce3e 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
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
   210
91756d20ce3e 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
|| *`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
   212
|| 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
   213
|| 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
   214
|| 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
   215
|| 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
   216
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   217
=== <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
   218
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
   219
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
   220
 * `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
   221
 * `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
   222
 * `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
   223
 * `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
   224
 * `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
   225
 * `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
   226
 * `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
   227
 * `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
   228
 * `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
   229
 * `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
   230
 * `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
   231
 * `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
   232
 * `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
   233
 * `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
   234
 * `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
   235
 * `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
   236
 * `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
   237
 * `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
   238
 * `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
   239
 * `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
   240
 * `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
   241
 * `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
   242
91756d20ce3e 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
`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
   244
91756d20ce3e 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
`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
   246
91756d20ce3e 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
`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
   248
91756d20ce3e 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
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
   250
91756d20ce3e 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
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
   252
91756d20ce3e 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
<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
   254
-- 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
   255
<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
   256
-- 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
   257
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   258
=== <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
   259
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
   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
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
   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
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
   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
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
   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">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
   268
-- 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
   269
<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
   270
-- 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
   271
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   272
=== <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
   273
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
   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
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
   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
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
   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
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
   280
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   281
=== <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
   282
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
   283
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   284
== 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
   285
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   286
=== <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
   287
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
   288
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   289
=== <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
   290
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
   291
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   292
=== <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
   293
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
   294
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
   295
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
   296
91756d20ce3e 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
<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
   298
  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
   299
</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
   300
<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
   301
  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
   302
</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
   303
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   304
=== <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
   305
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
   306
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   307
=== <tt>!SetInputMask(mask)</tt> ===
1796
8b10d405a1a0 LuaGameplay: Clarify controls input functions
Wuzzy
parents: 1794
diff changeset
   308
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
   309
91756d20ce3e 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
Example: 
1796
8b10d405a1a0 LuaGameplay: Clarify controls input functions
Wuzzy
parents: 1794
diff changeset
   311
<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
   312
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
   313
    -- 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
   314
    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
   315
		</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
   316
*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
   317
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
   318
*Note*: This function is used internally in the Animate [LuaLibraries library].
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
   319
91756d20ce3e 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
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
   321
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   322
=== <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
   323
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
   324
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   325
=== <tt>!SetVampiric(bool)</tt> (0.9.24) ===
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
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
   327
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   328
=== <tt>!GetVampiric()</tt> (0.9.25) ===
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
   329
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
   330
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   331
=== <tt>!SetLaserSight(bool)</tt> (0.9.24) ===
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
   332
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
   333
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   334
=== <tt>!GetLaserSight()</tt> (0.9.25) ===
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
   335
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
   336
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   337
=== <tt>!EnableSwitchHog()</tt> (0.9.25) ===
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
   338
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
   339
91756d20ce3e 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
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
   341
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
   342
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
   343
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   344
== Clans and teams ==
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   345
=== <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
   346
91756d20ce3e 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
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
   348
91756d20ce3e 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
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
   350
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
   351
`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
   352
91756d20ce3e 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
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
   354
1917
962f362690be LuaGameplay: Return value of AddTeam / AddMissionTeam
Wuzzy
parents: 1907
diff changeset
   355
 * `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
   356
 * `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
   357
 * `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
   358
 * `fort`: The name of the team’s fort (equals file name without the suffix and without the letter “L” or “R” before that suffix)
1919
d9cd57b53b6e LuaGameplay: Explain _qau
Wuzzy
parents: 1918
diff changeset
   359
 * `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
   360
 * `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
   361
1917
962f362690be LuaGameplay: Return value of AddTeam / AddMissionTeam
Wuzzy
parents: 1907
diff changeset
   362
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
   363
1778
4d4a119f1340 LuaGameplay: Fix clan color indent
Wuzzy
parents: 1777
diff changeset
   364
==== 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
   365
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
   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
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
   368
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
   369
 * `-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
   370
 * `-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
   371
 * `-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
   372
 * `-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
   373
 * `-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
   374
 * `-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
   375
 * `-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
   376
 * `-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
   377
 * `-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
   378
91756d20ce3e 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
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
   380
1919
d9cd57b53b6e LuaGameplay: Explain _qau
Wuzzy
parents: 1918
diff changeset
   381
==== Voicepack language ====
d9cd57b53b6e LuaGameplay: Explain _qau
Wuzzy
parents: 1918
diff changeset
   382
[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
   383
d9cd57b53b6e LuaGameplay: Explain _qau
Wuzzy
parents: 1918
diff changeset
   384
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).
d9cd57b53b6e LuaGameplay: Explain _qau
Wuzzy
parents: 1918
diff changeset
   385
d9cd57b53b6e LuaGameplay: Explain _qau
Wuzzy
parents: 1918
diff changeset
   386
We strongly recommend to always use the “_qau” suffix from version 1.0.0 on, unless you really want to force a particular language.
d9cd57b53b6e LuaGameplay: Explain _qau
Wuzzy
parents: 1918
diff changeset
   387
1778
4d4a119f1340 LuaGameplay: Fix clan color indent
Wuzzy
parents: 1777
diff changeset
   388
==== 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
   389
1919
d9cd57b53b6e LuaGameplay: Explain _qau
Wuzzy
parents: 1918
diff changeset
   390
<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
   391
--[[ 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
   392
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
   393
1917
962f362690be LuaGameplay: Return value of AddTeam / AddMissionTeam
Wuzzy
parents: 1907
diff changeset
   394
=== <tt>!AddMissionTeam(color)</tt> (1.0.0) ===
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
   395
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
   396
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
   397
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
   398
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
   399
1917
962f362690be LuaGameplay: Return value of AddTeam / AddMissionTeam
Wuzzy
parents: 1907
diff changeset
   400
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
   401
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
   402
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
   403
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
   404
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
   405
<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
   406
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
   407
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   408
=== <tt>!GetTeamName(teamIdx)</tt> (0.9.24) ===
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
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
   410
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   411
=== <tt>!GetTeamIndex(teamname)</tt> (0.9.24) ===
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
   412
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
   413
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   414
=== <tt>!GetTeamClan(teamname)</tt> (0.9.24) ===
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
   415
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
   416
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   417
=== <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
   418
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
   419
91756d20ce3e 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
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
   421
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   422
=== <tt>!SetTeamLabel(teamname[, label])</tt> (0.9.24) ===
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
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
   424
91756d20ce3e Separate core Lua stuff into new Lua pages for better maintainability. Main LuaAPI page not touched yet
Wuzzy <almikes@aol.com>
parents:
diff changeset
   425
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
   426
91756d20ce3e 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
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
   428
91756d20ce3e 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
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
   430
1777
e17942b0a485 LuaGameplay: Fix indent of SetTeamPassive
Wuzzy
parents: 1776
diff changeset
   431
=== <tt>SetTeamPassive(teamname, isPassive)</tt> (1.0.0) ===
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
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
   433
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   434
=== <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
   435
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
   436
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   437
=== <tt>!SetClanColor(clan, color)</tt> ===
1918
6ba186f18a73 LuaGameplay: Update SetClanColor
Wuzzy
parents: 1917
diff changeset
   438
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
   439
91756d20ce3e 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
Note: The stats graph does not support changing clan colors. 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`).
91756d20ce3e 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
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   442
== Campaign management ==
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   443
=== <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
   444
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
   445
91756d20ce3e 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
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
   447
1757
2c7eba50e7b0 LuaGameplay: Redo headers
Wuzzy
parents: 1754
diff changeset
   448
=== <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
   449
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
   450
1937
55255a1feba7 LuaGameplay: Fix version of *MissionVar
Wuzzy
parents: 1919
diff changeset
   451
=== <tt>!SaveMissionVar(varname, value)</tt> (1.0.0) ===
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
   452
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
   453
1937
55255a1feba7 LuaGameplay: Fix version of *MissionVar
Wuzzy
parents: 1919
diff changeset
   454
=== <tt>!GetMissionVar(varname)</tt> (1.0.0) ===
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
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
   456
1779
9cb32a3519ee LuaGameplay: Move GetRandom to bottom
Wuzzy
parents: 1778
diff changeset
   457
== Randomness ==
9cb32a3519ee LuaGameplay: Move GetRandom to bottom
Wuzzy
parents: 1778
diff changeset
   458
=== <tt>!GetRandom(number)</tt> ===
9cb32a3519ee LuaGameplay: Move GetRandom to bottom
Wuzzy
parents: 1778
diff changeset
   459
Returns a randomly generated number in the range of 0 to number - 1. This random number uses the game seed, so is synchronised, and thus safe for multiplayer and saved games. 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`.