1 #summary List of gameplay-related functions in the Lua API

     1 #summary List of gameplay-related functions in the Lua API

     2 

     2 

     3 = Lua API: Gameplay functions =

     3 = Lua API: Gameplay functions =

     4 This page is a list of all gameplay-related functions in the [LuaAPI Lua API].

     4 This page is a list of all gameplay-related functions in the [LuaAPI Lua API].

     5 

     5 

     9 Disables *all* !GameFlags.

    11 Disables *all* !GameFlags.

    10 

    12 

    12 Disables the listed !GameFlags, without changing the status of other !GameFlags.

    14 Disables the listed !GameFlags, without changing the status of other !GameFlags.

    13 

    15 

    15 Enables the listed !GameFlags, without changing the status of other !GameFlags. In missions, no !GameFlags are set initially.

    17 Enables the listed !GameFlags, without changing the status of other !GameFlags. In missions, no !GameFlags are set initially.

    16 

    18 

    18 Returns `true` if the specified gameflag is enabled, otherwise `false`.

    20 Returns `true` if the specified gameflag is enabled, otherwise `false`.

    19 

    21 

    22 Forces the current hedgehog to skip its turn.

    24 Forces the current hedgehog to skip its turn.

    23 

    25 

    25 Ends the current turn immediately.

    27 Ends the current turn immediately.

    26 

    28 

    27 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.

    29 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.

    28 

    30 

    30 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.

    32 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.

    31 

    33 

    32 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`.

    34 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`.

    33 

    35 

    34 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.

    36 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.

    35 

    37 

    36 Note: If you want the turn to end instantly, it is recommended to use `EndTurn` instead.

    38 Note: If you want the turn to end instantly, it is recommended to use `EndTurn` instead.

    37 

    39 

    39 Set the remaining turn time in milliseconds. The current remaining turn time can be read from the variable `TurnTimeLeft`.

    41 Set the remaining turn time in milliseconds. The current remaining turn time can be read from the variable `TurnTimeLeft`.

    40 

    42 

    42 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`.

    44 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`.

    43 

    45 

    45 Pauses the turn time indefinitely if `isPaused` is set to `true`, disabled the turn time pause if `isPaused` is set to `false`.

    47 Pauses the turn time indefinitely if `isPaused` is set to `true`, disabled the turn time pause if `isPaused` is set to `false`.

    46 

    48 

    48 Returns `true` if the turn time is currently paused by `SetTurnTimePaused`, otherwise returns `false`.

    50 Returns `true` if the turn time is currently paused by `SetTurnTimePaused`, otherwise returns `false`.

    49 

    51 

    51 Makes the game end.

    53 Makes the game end.

    52 

    54 

    55 Changes the current gravity of the game in percent (relative to default, integer value).

    57 Changes the current gravity of the game in percent (relative to default, integer value).

    56 Setting it to 100 will set gravity to default gravity of Hedgewars, 200 will double it, etc.

    58 Setting it to 100 will set gravity to default gravity of Hedgewars, 200 will double it, etc.

    57 

    59 

    59 Returns the current gravity in percent.

    61 Returns the current gravity in percent.

    60 

    62 

    62 Sets the water level (`WaterLine`) to the specified y-coordinate.

    64 Sets the water level (`WaterLine`) to the specified y-coordinate.

    63 

    65 

    65 Sets the current wind in the range of -100 to 100 inclusive. Use together with `gfDisableWind` for full control.

    67 Sets the current wind in the range of -100 to 100 inclusive. Use together with `gfDisableWind` for full control.

    66 

    68 

    68 Returns current wind, expressed as a floating point number between -100 to 100 inclusive. Note there may be rounding errors.

    70 Returns current wind, expressed as a floating point number between -100 to 100 inclusive. Note there may be rounding errors.

    69 

    71 

    71 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.

    73 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.

    72 

    74 

    74 Cause an explosion or erase land, push or damage gears.

    76 Cause an explosion or erase land, push or damage gears.

    75 

    77 

    76 By default, an explosion destroys a circular piece of land and damages and pushes gears in its radius.

    78 By default, an explosion destroys a circular piece of land and damages and pushes gears in its radius.

    77 

    79 

    78 The explosion occurs at coordinates `(x, y)` with the given `radius`. Assuming 100% damage, the explosion damage at the center equals the explosion radius.

    80 The explosion occurs at coordinates `(x, y)` with the given `radius`. Assuming 100% damage, the explosion damage at the center equals the explosion radius.

   106 

   108 

   107 -- Erase a circle of land without side effects

   109 -- Erase a circle of land without side effects

   108 Explode(500, 100, 100, EXPLNoDamage + EXPLDoNotTouchAny + EXPLNoGfx)

   110 Explode(500, 100, 100, EXPLNoDamage + EXPLDoNotTouchAny + EXPLNoGfx)

   109 </code>

   111 </code>

   110 

   112 

   113 This updates the settings (initial ammo, crate probability, etc.) for a specified [AmmoTypes ammo type]. This must only be used in the `onAmmoStoreInit()` event handler. In other places, this function will not work.

   115 This updates the settings (initial ammo, crate probability, etc.) for a specified [AmmoTypes ammo type]. This must only be used in the `onAmmoStoreInit()` event handler. In other places, this function will not work.

   114 

   116 

   115 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!

   117 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!

   116 

   118 

   117 Parameters:

   119 Parameters:

   128     SetAmmo(amGrenade, 0, 0, 0, 3) -- crates should contain always three grenade

   130     SetAmmo(amGrenade, 0, 0, 0, 3) -- crates should contain always three grenade

   129     SetAmmo(amSkip, 9, 0, 0, 0) -- enable skip</code>

   131     SetAmmo(amSkip, 9, 0, 0, 0) -- enable skip</code>

   130 

   132 

   131 Hint: It is recommended to always enable skip in missions. Only in exceptional circumstances you should choose to not enable skip.

   133 Hint: It is recommended to always enable skip in missions. Only in exceptional circumstances you should choose to not enable skip.

   132 

   134 

   134 Returns ammo settings (initial ammo, crate probability, etc.) for a specified [AmmoTypes ammo type]. This function is analogue to `SetAmmo`.

   136 Returns ammo settings (initial ammo, crate probability, etc.) for a specified [AmmoTypes ammo type]. This function is analogue to `SetAmmo`.

   135 

   137 

   136 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.

   138 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.

   137 

   139 

   138 Example:

   140 Example:

   139 

   141 

   140 <code language="lua">count, prob, delay, numberInCrate = GetAmmo(amGrenade) -- Get ammo settings of amGrenade</code>

   142 <code language="lua">count, prob, delay, numberInCrate = GetAmmo(amGrenade) -- Get ammo settings of amGrenade</code>

   141 

   143 

   143 Changes the delay of a specified [AmmoTypes Ammo Type].

   145 Changes the delay of a specified [AmmoTypes Ammo Type].

   144 

   146 

   146 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`.

   148 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`.

   147 

   149 

   148  * `ammoType`: The ammo type to set the text for

   150  * `ammoType`: The ammo type to set the text for

   149  * `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.

   151  * `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.

   150  * `caption`: The second line in the ammo menu (below the title). E.g. “Timed grenade” for `amGrenade`.

   152  * `caption`: The second line in the ammo menu (below the title). E.g. “Timed grenade” for `amGrenade`.

   156 Example:

   158 Example:

   157 <code language="lua">

   159 <code language="lua">

   158 -- Overwrites bazooka name and description

   160 -- Overwrites bazooka name and description

   159 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>

   161 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>

   160 

   162 

   162 Will set a string `descAppend` to be appended below the “core” description (ammo tooltip) of the specified `ammoType`, without changing the ordinary description.

   164 Will set a string `descAppend` to be appended below the “core” description (ammo tooltip) of the specified `ammoType`, without changing the ordinary description.

   163 Note that calling this function always sets the complete appended string, you can't use this function to append multiple texts in row.

   165 Note that calling this function always sets the complete appended string, you can't use this function to append multiple texts in row.

   164 

   166 

   165 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.

   167 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.

   166 

   168 

   167 Example:

   169 Example:

   168 <code language="lua">

   170 <code language="lua">

   169 -- Appends a text to the ammo tooltip of the bazooka but leaves name and main description intact

   171 -- Appends a text to the ammo tooltip of the bazooka but leaves name and main description intact

   170 SetAmmoTexts(amBazooka, "This weapon deals double the damage than usually.")</code>

   172 SetAmmoTexts(amBazooka, "This weapon deals double the damage than usually.")</code>

   171 

   173 

   173 Adds `ammoType` to the specified gear. The amount added is determined by the arguments passed via `SetAmmo()` in the `onAmmoStoreInit()` 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.

   175 Adds `ammoType` to the specified gear. The amount added is determined by the arguments passed via `SetAmmo()` in the `onAmmoStoreInit()` 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.

   174 

   176 

   175 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`.

   177 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`.

   176 

   178 

   178 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`.

   180 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`.

   179 

   181 

   182 Returns `true`/`false` if the map has a border or not.

   184 Returns `true`/`false` if the map has a border or not.

   183 

   185 

   185 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.).

   187 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.).

   186 

   188 

   188 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.

   190 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.

   189 

   191 

   190 These are the accepted values for `frameIdx`:

   192 These are the accepted values for `frameIdx`:

   191 

   193 

   192 || *`frameIdx`* || *Length* || *Orientation* ||

   194 || *`frameIdx`* || *Length* || *Orientation* ||

   197 || 4 || long || horizontal ||

   199 || 4 || long || horizontal ||

   198 || 5 || long || decreasing right ||

   200 || 5 || long || decreasing right ||

   199 || 6 || long || vertical ||

   201 || 6 || long || vertical ||

   200 || 7 || long || increasing right ||

   202 || 7 || long || increasing right ||

   201 

   203 

   203 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.

   205 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.

   204 

   206 

   205 These are the accepted values for `frameIdx`:

   207 These are the accepted values for `frameIdx`:

   206 

   208 

   207 || *`frameIdx`* || *Orientation* ||

   209 || *`frameIdx`* || *Orientation* ||

   208 || 0 || horizontal ||

   210 || 0 || horizontal ||

   209 || 1 || decreasing right ||

   211 || 1 || decreasing right ||

   210 || 2 || vertical ||

   212 || 2 || vertical ||

   211 || 3 || increasing right ||

   213 || 3 || increasing right ||

   212 

   214 

   214 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:

   216 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:

   215 

   217 

   216  * `sprAmGirder`

   218  * `sprAmGirder`

   217  * `sprAmRubber`

   219  * `sprAmRubber`

   218  * `sprAMSlot`

   220  * `sprAMSlot`

   249 <code language="lua">PlaceSprite(2836, 634, sprAmGirder, 5)

   251 <code language="lua">PlaceSprite(2836, 634, sprAmGirder, 5)

   250 -- Places the girder sprite as normal terrain at (2836, 634). The `frameIdx` 5 is for the long decreasing right girder.</code>

   252 -- Places the girder sprite as normal terrain at (2836, 634). The `frameIdx` 5 is for the long decreasing right girder.</code>

   251 <code language="lua">PlaceSprite(1411, 625, sprAmRubber, 1, nil, nil, nil, nil, lfBouncy)

   253 <code language="lua">PlaceSprite(1411, 625, sprAmRubber, 1, nil, nil, nil, nil, lfBouncy)

   252 -- Places the rubber band sprite as bouncy terrain at (2836, 634). The `frameIdx` 1 is for the decreasing right rubber band.</code>

   254 -- Places the rubber band sprite as bouncy terrain at (2836, 634). The `frameIdx` 1 is for the decreasing right rubber band.</code>

   253 

   255 

   255 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.

   257 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.

   256 

   258 

   257 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.

   259 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.

   258 

   260 

   259 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.

   261 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.

   263 <code language="lua">EraseSprite(2836, 634, sprAmGirder, 5)

   265 <code language="lua">EraseSprite(2836, 634, sprAmGirder, 5)

   264 -- Removes the girder sprite at (2836, 634). The frameIdx 5 is for the long decreasing right girder.</code>

   266 -- Removes the girder sprite at (2836, 634). The frameIdx 5 is for the long decreasing right girder.</code>

   265 <code language="lua">EraseSprite(1411, 625, sprAmRubber, 1, true, true, nil, nil, lfIndestructible)

   267 <code language="lua">EraseSprite(1411, 625, sprAmRubber, 1, true, true, nil, nil, lfIndestructible)

   266 -- Removes indestructibility from a rubber band sprite at (2836, 634). The frameIdx 1 is for the decreasing right rubber band.</code>

   268 -- Removes indestructibility from a rubber band sprite at (2836, 634). The frameIdx 1 is for the decreasing right rubber band.</code>

   267 

   269 

   269 This function is used to draw your own maps using Lua. The maps drawn with this are of type “hand-drawn”.

   271 This function is used to draw your own maps using Lua. The maps drawn with this are of type “hand-drawn”.

   270 

   272 

   271 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).

   273 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).

   272 

   274 

   273 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.

   275 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.

   274 

   276 

   275 See [LuaDrawning] for some examples.

   277 See [LuaDrawning] for some examples.

   276 

   278 

   278 Makes sure that all the points/lines specified using `AddPoint` are actually applied to the map. This function must be called within `onGameInit`.

   280 Makes sure that all the points/lines specified using `AddPoint` are actually applied to the map. This function must be called within `onGameInit`.

   279 

   281 

   283 Returns the currently selected [AmmoTypes Ammo Type].

   285 Returns the currently selected [AmmoTypes Ammo Type].

   284 

   286 

   286 This function will switch to the hedgehog with the specifiedd `gearUid`.

   288 This function will switch to the hedgehog with the specifiedd `gearUid`.

   287 

   289 

   289 Sets the selected weapon of `CurrentHedgehog` to one of the [AmmoTypes Ammo Type].

   291 Sets the selected weapon of `CurrentHedgehog` to one of the [AmmoTypes Ammo Type].

   290 

   292 

   291 Examples:

   293 Examples:

   292 

   294 

   293 <code language="lua">

   295 <code language="lua">

   295 </code>

   297 </code>

   296 <code language="lua">

   298 <code language="lua">

   297   SetWeapon(amNothing) -- unselects the weapon.

   299   SetWeapon(amNothing) -- unselects the weapon.

   298 </code>

   300 </code>

   299 

   301 

   301 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.

   303 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.

   302 

   304 

   304 Masks specified player input. This means that Hedgewars ignores certain player inputs, such as walking or jumping.

   306 Masks specified player input. This means that Hedgewars ignores certain player inputs, such as walking or jumping.

   305 

   307 

   306 Example: 

   308 Example: 

   307 <code language="lua">    -- masks the long and high jump commands

   309 <code language="lua">    -- masks the long and high jump commands

   308 SetInputMask(band(0xFFFFFFFF, bnot(gmLJump + gmHJump))) 

   310 SetInputMask(band(0xFFFFFFFF, bnot(gmLJump + gmHJump))) 

   313 

   315 

   314 *Note*: This function is used internally in the Animate [LuaLibraries library].

   316 *Note*: This function is used internally in the Animate [LuaLibraries library].

   315 

   317 

   316 See also [GearMessages].

   318 See also [GearMessages].

   317 

   319 

   319 Returns the current input mask of the player.

   321 Returns the current input mask of the player.

   320 

   322 

   322 Toggles vampirism mode for this turn. Set `bool` to `true` to enable (same effect as if the hedgehog has used Vampirism), `false` to disable.

   324 Toggles vampirism mode for this turn. Set `bool` to `true` to enable (same effect as if the hedgehog has used Vampirism), `false` to disable.

   323 

   325 

   325 Returns true if vampirism mode is currently active.

   327 Returns true if vampirism mode is currently active.

   326 

   328 

   328 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.

   330 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.

   329 

   331 

   331 Returns true if laser sight (as utility) is currently active. The sniper rifle's built-in laser sight does not count.

   333 Returns true if laser sight (as utility) is currently active. The sniper rifle's built-in laser sight does not count.

   332 

   334 

   334 Enable hog switching mode for the current hedgehog. This function should be called while the hedgehog is standing on solid ground (`GetFlightTime` returns 0).

   336 Enable hog switching mode for the current hedgehog. This function should be called while the hedgehog is standing on solid ground (`GetFlightTime` returns 0).

   335 

   337 

   336 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.

   338 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.

   337 

   339 

   338 On success, returns the `gtSwitcher` gear being spawned or, if hog switching mode is already active, returns the exsting gear. On failure, returns `nil`.

   340 On success, returns the `gtSwitcher` gear being spawned or, if hog switching mode is already active, returns the exsting gear. On failure, returns `nil`.

   339 

   341 

   342 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`.

   344 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`.

   343 

   345 

   346 

   348 

   347 Adds a new team.

   349 Adds a new team.

   348 

   350 

   349 You *must* call it only in `onGameInit`.

   351 You *must* call it only in `onGameInit`.

   350 You *must* add at least one hedgehog with `AddHog` after calling this. The engine does not support empty teams.

   352 You *must* add at least one hedgehog with `AddHog` after calling this. The engine does not support empty teams.

   357  * `grave`: The name of the team’s grave (equals file name without the suffix)

   359  * `grave`: The name of the team’s grave (equals file name without the suffix)

   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)

   360  * `fort`: The name of the team’s fort (equals file name without the suffix and without the letter “L” or “R” before that suffix)

   359  * `voicepack`: The name of the team’s voice pack (equals the directory name)

   361  * `voicepack`: The name of the team’s voice pack (equals the directory name)

   360  * `flag`: Optional argument for the name of the team’s flag (equals file name without the suffix). If set to `nil`, the flag “hedgewars” is used.

   362  * `flag`: Optional argument for the name of the team’s flag (equals file name without the suffix). If set to `nil`, the flag “hedgewars” is used.

   361 

   363 

   363 Each team must have a color. The color also determines clan membership: Teams with equal color are in the same clan.

   365 Each team must have a color. The color also determines clan membership: Teams with equal color are in the same clan.

   364 

   366 

   365 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:

   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:

   366 

   368 

   367  * `-1`: red

   369  * `-1`: red

   374  * `-8`: brown

   376  * `-8`: brown

   375  * `-9`: yellow

   377  * `-9`: yellow

   376 

   378 

   377 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. 

   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. 

   378 

   380 

   380 

   382 

   381 <code language="lua">AddTeam("team 1", -1, "Simple", "Tank", "Default", "hedgewars")

   383 <code language="lua">AddTeam("team 1", -1, "Simple", "Tank", "Default", "hedgewars")

   382 --[[ Adds a new team with name “team 1”, the first default color (usually red), the grave “Simple”,

   384 --[[ Adds a new team with name “team 1”, the first default color (usually red), the grave “Simple”,

   383 the fort “Tank” the voicepack “Default” and the flag “hedgewars”. ]]</code>

   385 the fort “Tank” the voicepack “Default” and the flag “hedgewars”. ]]</code>

   384 

   386 

   386 Adds a new team using the player-chosen team identity when playing a singleplayer mission. Does not work in multiplayer.

   388 Adds a new team using the player-chosen team identity when playing a singleplayer mission. Does not work in multiplayer.

   387 

   389 

   388 This function is very similar to `AddTeam`. Team settings like team name and flag will be taken from the player-chosen team.

   390 This function is very similar to `AddTeam`. Team settings like team name and flag will be taken from the player-chosen team.

   389 You only need to specify the clan color, which has the same meaning as in `AddTeam`.

   391 You only need to specify the clan color, which has the same meaning as in `AddTeam`.

   390 

   392 

   392 

   394 

   393 Example:

   395 Example:

   394 <code language="lua">-- Add mission team with default clan color

   396 <code language="lua">-- Add mission team with default clan color

   395 AddMissionTeam(-1)</code>

   397 AddMissionTeam(-1)</code>

   396 

   398 

   398 Returns the name of the team with the index `teamIdx`. `teamIdx` is a number between 0 and `TeamsCount-1`.

   400 Returns the name of the team with the index `teamIdx`. `teamIdx` is a number between 0 and `TeamsCount-1`.

   399 

   401 

   401 Returns the team index (number between 0 and `TeamsCount-1`) of the team with the name `teamName`.

   403 Returns the team index (number between 0 and `TeamsCount-1`) of the team with the name `teamName`.

   402 

   404 

   404 Returns the clan ID of the team with the given `teamName`.

   406 Returns the clan ID of the team with the given `teamName`.

   405 

   407 

   407 Vaporizes all the hogs of the team with the given team name in a puff of smoke.

   409 Vaporizes all the hogs of the team with the given team name in a puff of smoke.

   408 

   410 

   409 This function must not be called while it's the team's turn.

   411 This function must not be called while it's the team's turn.

   410 

   412 

   412 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.

   414 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.

   413 

   415 

   414 If `label` is `nil`, the label will be removed.

   416 If `label` is `nil`, the label will be removed.

   415 

   417 

   416 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.

   418 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.

   417 

   419 

   418 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.

   420 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.

   419 

   421 

   421 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.

   423 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.

   422 

   424 

   424 Returns the RGBA color of the chosen clan by its number. The color data type is described in [LuaOverview#Color].

   426 Returns the RGBA color of the chosen clan by its number. The color data type is described in [LuaOverview#Color].

   425 

   427 

   427 Sets the RGBA color of the chosen clan by its number. The color data type is described in [LuaOverview#Color]. 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).

   429 Sets the RGBA color of the chosen clan by its number. The color data type is described in [LuaOverview#Color]. 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).

   428 

   430 

   429 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`).

   431 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`).

   430 

   432 

   433 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]).

   435 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]).

   434 

   436 

   435 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].

   437 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].

   436 

   438 

   438 Returns the value of the campaign variable `varname` as a string. See also `SaveCampaignVar`.

   440 Returns the value of the campaign variable `varname` as a string. See also `SaveCampaignVar`.

   439 

   441 

   441 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.

   443 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.

   442 

   444 

   444 Returns the value of the mission variable `varname` as a string. See also `SaveMissionVar`.

   446 Returns the value of the mission variable `varname` as a string. See also `SaveMissionVar`.

   445 

   447