# HG changeset patch # User Wuzzy # Date 1555502227 -3600 # Node ID 2c7eba50e7b00076787f2e6fd38681b22b5c06d1 # Parent 66b51b8ba202058221e918f47495ccf9246be75f LuaGameplay: Redo headers diff -r 66b51b8ba202 -r 2c7eba50e7b0 LuaGameplay.wiki --- a/LuaGameplay.wiki Wed Apr 17 12:54:45 2019 +0100 +++ b/LuaGameplay.wiki Wed Apr 17 12:57:07 2019 +0100 @@ -3,30 +3,32 @@ = Lua API: Gameplay functions = This page is a list of all gameplay-related functions in the [LuaAPI Lua API]. -=== `GameFlags` functions === + -==== !ClearGameFlags() ==== +== `GameFlags` functions == + +=== !ClearGameFlags() === Disables *all* !GameFlags. -==== !DisableGameFlags(gameflag, ...) ==== +=== !DisableGameFlags(gameflag, ...) === Disables the listed !GameFlags, without changing the status of other !GameFlags. -==== !EnableGameFlags(gameflag, ...) ==== +=== !EnableGameFlags(gameflag, ...) === Enables the listed !GameFlags, without changing the status of other !GameFlags. In missions, no !GameFlags are set initially. -==== !GetGameFlag(gameflag) ==== +=== !GetGameFlag(gameflag) === Returns `true` if the specified gameflag is enabled, otherwise `false`. -=== Turns === -==== SkipTurn() (0.9.24) ==== +== Turns == +=== SkipTurn() (0.9.24) === Forces the current hedgehog to skip its turn. -==== EndTurn([noTaunts]) (0.9.23) ==== +=== EndTurn([noTaunts]) (0.9.23) === Ends the current turn immediately. 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. -==== Retreat(time [, respectGetAwayTimeFactor) (0.9.25) ==== +=== Retreat(time [, respectGetAwayTimeFactor) (0.9.25) === 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. 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`. @@ -35,42 +37,42 @@ Note: If you want the turn to end instantly, it is recommended to use `EndTurn` instead. -==== !SetTurnTimeLeft(newTurnTimeLeft) (0.9.25) ==== +=== !SetTurnTimeLeft(newTurnTimeLeft) (0.9.25) === Set the remaining turn time in milliseconds. The current remaining turn time can be read from the variable `TurnTimeLeft`. -==== !SetReadyTimeLeft(newReadyTimeLeft) (0.9.25) ==== +=== !SetReadyTimeLeft(newReadyTimeLeft) (0.9.25) === 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`. -==== !SetTurnTimePaused(isPaused) (0.9.25) ==== +=== !SetTurnTimePaused(isPaused) (0.9.25) === Pauses the turn time indefinitely if `isPaused` is set to `true`, disabled the turn time pause if `isPaused` is set to `false`. -==== !GetTurnTimePaused() (0.9.25) ==== +=== !GetTurnTimePaused() (0.9.25) === Returns `true` if the turn time is currently paused by `SetTurnTimePaused`, otherwise returns `false`. -==== !EndGame() ==== +=== !EndGame() === Makes the game end. -=== Environment === -==== !SetGravity(percent) ==== +== Environment == +=== !SetGravity(percent) === Changes the current gravity of the game in percent (relative to default, integer value). Setting it to 100 will set gravity to default gravity of Hedgewars, 200 will double it, etc. -==== !GetGravity() ==== +=== !GetGravity() === Returns the current gravity in percent. -==== !SetWaterLine(waterline) ==== +=== !SetWaterLine(waterline) === Sets the water level (`WaterLine`) to the specified y-coordinate. -==== !SetWind(windSpeed) ==== +=== !SetWind(windSpeed) === Sets the current wind in the range of -100 to 100 inclusive. Use together with `gfDisableWind` for full control. -==== !GetWind() (0.9.24) ==== +=== !GetWind() (0.9.24) === Returns current wind, expressed as a floating point number between -100 to 100 inclusive. Note there may be rounding errors. -==== !SetMaxBuildDistance(distInPx) ==== +=== !SetMaxBuildDistance(distInPx) === 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. -==== Explode(x, y, radius[, options]) (0.9.24) ==== +=== Explode(x, y, radius[, options]) (0.9.24) === Cause an explosion or erase land, push or damage gears. By default, an explosion destroys a circular piece of land and damages and pushes gears in its radius. @@ -108,8 +110,8 @@ Explode(500, 100, 100, EXPLNoDamage + EXPLDoNotTouchAny + EXPLNoGfx) -=== Ammo === -==== !SetAmmo(ammoType, count, probability, delay, numberInCrate) ==== +== Ammo == +=== !SetAmmo(ammoType, count, probability, delay, numberInCrate) === 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. 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! @@ -130,7 +132,7 @@ Hint: It is recommended to always enable skip in missions. Only in exceptional circumstances you should choose to not enable skip. -==== !GetAmmo(ammoType) ==== +=== !GetAmmo(ammoType) === Returns ammo settings (initial ammo, crate probability, etc.) for a specified [AmmoTypes ammo type]. This function is analogue to `SetAmmo`. 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. @@ -139,10 +141,10 @@ count, prob, delay, numberInCrate = GetAmmo(amGrenade) -- Get ammo settings of amGrenade -==== !SetAmmoDelay(ammoType, delay) ==== +=== !SetAmmoDelay(ammoType, delay) === Changes the delay of a specified [AmmoTypes Ammo Type]. -==== !SetAmmoTexts(ammoType, name, caption, description [, showExtra]) (0.9.23) ==== +=== !SetAmmoTexts(ammoType, name, caption, description [, showExtra]) (0.9.23) === 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`. * `ammoType`: The ammo type to set the text for @@ -158,7 +160,7 @@ -- Overwrites bazooka name and description SetAmmoTexts(amBazooka, "Spoon Missile", "Crazy weapon", "This crazy weapon looks like a spoon and explodes on impact.|Attack: Hold to launch with more power") -==== !SetAmmoDescriptionAppendix(ammoType, descAppend) (0.9.23) ==== +=== !SetAmmoDescriptionAppendix(ammoType, descAppend) (0.9.23) === Will set a string `descAppend` to be appended below the “core” description (ammo tooltip) of the specified `ammoType`, without changing the ordinary description. Note that calling this function always sets the complete appended string, you can't use this function to append multiple texts in row. @@ -169,22 +171,22 @@ -- Appends a text to the ammo tooltip of the bazooka but leaves name and main description intact SetAmmoTexts(amBazooka, "This weapon deals double the damage than usually.") -==== !AddAmmo(gearUid, ammoType, ammoCount) ==== +=== !AddAmmo(gearUid, ammoType, ammoCount) === 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. 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`. -==== !GetAmmoName(ammoType [, ignoreOverwrite ]) (0.9.23) ==== +=== !GetAmmoName(ammoType [, ignoreOverwrite ]) (0.9.23) === 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`. -=== Map === -==== !MapHasBorder() ==== +== Map == +=== !MapHasBorder() === Returns `true`/`false` if the map has a border or not. -==== !TestRectForObstacle(x1, y1, x2, y2, landOnly) ==== +=== !TestRectForObstacle(x1, y1, x2, y2, landOnly) === 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.). -==== !PlaceGirder(x, y, frameIdx) ==== +=== !PlaceGirder(x, y, frameIdx) === 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. These are the accepted values for `frameIdx`: @@ -199,7 +201,7 @@ || 6 || long || vertical || || 7 || long || increasing right || -==== !PlaceRubber(x, y, frameIdx) (0.9.23) ==== +=== !PlaceRubber(x, y, frameIdx) (0.9.23) === 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. These are the accepted values for `frameIdx`: @@ -210,7 +212,7 @@ || 2 || vertical || || 3 || increasing right || -==== !PlaceSprite(x, y, sprite, frameIdx, tint, behind, flipHoriz, flipVert, [, landFlag, ...]) ==== +=== !PlaceSprite(x, y, sprite, frameIdx, tint, behind, flipHoriz, flipVert, [, landFlag, ...]) === 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: * `sprAmGirder` @@ -251,7 +253,7 @@ PlaceSprite(1411, 625, sprAmRubber, 1, nil, nil, nil, nil, lfBouncy) -- Places the rubber band sprite as bouncy terrain at (2836, 634). The `frameIdx` 1 is for the decreasing right rubber band. -==== !EraseSprite(x, y, sprite, frameIdx, eraseOnLFMatch, onlyEraseLF, flipHoriz, flipVert, [, landFlag, ...]) ==== +=== !EraseSprite(x, y, sprite, frameIdx, eraseOnLFMatch, onlyEraseLF, flipHoriz, flipVert, [, landFlag, ...]) === 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. 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. @@ -265,7 +267,7 @@ EraseSprite(1411, 625, sprAmRubber, 1, true, true, nil, nil, lfIndestructible) -- Removes indestructibility from a rubber band sprite at (2836, 634). The frameIdx 1 is for the decreasing right rubber band. -==== !AddPoint(x, y [, width [, erase] ]) ==== +=== !AddPoint(x, y [, width [, erase] ]) === This function is used to draw your own maps using Lua. The maps drawn with this are of type “hand-drawn”. 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). @@ -274,18 +276,18 @@ See [LuaDrawning] for some examples. -==== !FlushPoints() ==== +=== !FlushPoints() === Makes sure that all the points/lines specified using `AddPoint` are actually applied to the map. This function must be called within `onGameInit`. -=== Current hedgehog === +== Current hedgehog == -==== !GetCurAmmoType() ==== +=== !GetCurAmmoType() === Returns the currently selected [AmmoTypes Ammo Type]. -==== !SwitchHog(gearUid) ==== +=== !SwitchHog(gearUid) === This function will switch to the hedgehog with the specifiedd `gearUid`. -==== !SetWeapon(ammoType) ==== +=== !SetWeapon(ammoType) === Sets the selected weapon of `CurrentHedgehog` to one of the [AmmoTypes Ammo Type]. Examples: @@ -297,10 +299,10 @@ SetWeapon(amNothing) -- unselects the weapon. -==== !SetNextWeapon() ==== +=== !SetNextWeapon() === 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. -==== !SetInputMask(mask) ==== +=== !SetInputMask(mask) === Masks specified player input. This means that Hedgewars ignores certain player inputs, such as walking or jumping. Example: @@ -315,34 +317,34 @@ See also [GearMessages]. -==== !GetInputMask() ==== +=== !GetInputMask() === Returns the current input mask of the player. -==== !SetVampiric(bool) (0.9.24) ==== +=== !SetVampiric(bool) (0.9.24) === Toggles vampirism mode for this turn. Set `bool` to `true` to enable (same effect as if the hedgehog has used Vampirism), `false` to disable. -==== !GetVampiric() (0.9.25) ==== +=== !GetVampiric() (0.9.25) === Returns true if vampirism mode is currently active. -==== !SetLaserSight(bool) (0.9.24) ==== +=== !SetLaserSight(bool) (0.9.24) === 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. -==== !GetLaserSight() (0.9.25) ==== +=== !GetLaserSight() (0.9.25) === Returns true if laser sight (as utility) is currently active. The sniper rifle's built-in laser sight does not count. -==== !EnableSwitchHog() (0.9.25) ==== +=== !EnableSwitchHog() (0.9.25) === Enable hog switching mode for the current hedgehog. This function should be called while the hedgehog is standing on solid ground (`GetFlightTime` returns 0). 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. On success, returns the `gtSwitcher` gear being spawned or, if hog switching mode is already active, returns the exsting gear. On failure, returns `nil`. -=== Randomness === -==== !GetRandom(number) ==== +== Randomness == +=== !GetRandom(number) === 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`. -=== Clans and teams === -==== !AddTeam(teamname, color, grave, fort, voicepack, flag) ==== +== Clans and teams == +=== !AddTeam(teamname, color, grave, fort, voicepack, flag) === Adds a new team. @@ -359,7 +361,7 @@ * `voicepack`: The name of the team’s voice pack (equals the directory name) * `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. -===== Clan color ===== +=== Clan color === Each team must have a color. The color also determines clan membership: Teams with equal color are in the same clan. 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: @@ -376,13 +378,13 @@ 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. -===== Example ===== +=== Example === AddTeam("team 1", -1, "Simple", "Tank", "Default", "hedgewars") --[[ Adds a new team with name “team 1”, the first default color (usually red), the grave “Simple”, the fort “Tank” the voicepack “Default” and the flag “hedgewars”. ]] -==== !AddMissionTeam(color) (0.9.25) ==== +=== !AddMissionTeam(color) (0.9.25) === Adds a new team using the player-chosen team identity when playing a singleplayer mission. Does not work in multiplayer. This function is very similar to `AddTeam`. Team settings like team name and flag will be taken from the player-chosen team. @@ -394,21 +396,21 @@ -- Add mission team with default clan color AddMissionTeam(-1) -==== !GetTeamName(teamIdx) (0.9.24) ==== +=== !GetTeamName(teamIdx) (0.9.24) === Returns the name of the team with the index `teamIdx`. `teamIdx` is a number between 0 and `TeamsCount-1`. -==== !GetTeamIndex(teamname) (0.9.24) ==== +=== !GetTeamIndex(teamname) (0.9.24) === Returns the team index (number between 0 and `TeamsCount-1`) of the team with the name `teamName`. -==== !GetTeamClan(teamname) (0.9.24) ==== +=== !GetTeamClan(teamname) (0.9.24) === Returns the clan ID of the team with the given `teamName`. -==== !DismissTeam(teamname) ==== +=== !DismissTeam(teamname) === Vaporizes all the hogs of the team with the given team name in a puff of smoke. This function must not be called while it's the team's turn. -==== !SetTeamLabel(teamname[, label]) (0.9.24) ==== +=== !SetTeamLabel(teamname[, label]) (0.9.24) === 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. If `label` is `nil`, the label will be removed. @@ -417,29 +419,29 @@ 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. -=== SetTeamPassive(teamname, isPassive) (1.0.0) === +== SetTeamPassive(teamname, isPassive) (1.0.0) == 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. -==== !GetClanColor(clan) ==== +=== !GetClanColor(clan) === Returns the RGBA color of the chosen clan by its number. The color data type is described in [LuaOverview#Color]. -==== !SetClanColor(clan, color) ==== +=== !SetClanColor(clan, color) === 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). 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`). -=== Campaign management === -==== !SaveCampaignVar(varname, value) ==== +== Campaign management == +=== !SaveCampaignVar(varname, value) === 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]). 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]. -==== !GetCampaignVar(varname) ==== +=== !GetCampaignVar(varname) === Returns the value of the campaign variable `varname` as a string. See also `SaveCampaignVar`. -==== !SaveMissionVar(varname, value) (0.9.25) ==== +=== !SaveMissionVar(varname, value) (0.9.25) === 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. -==== !GetMissionVar(varname) (0.9.25) ==== +=== !GetMissionVar(varname) (0.9.25) === Returns the value of the mission variable `varname` as a string. See also `SaveMissionVar`.