#summary Global variables in the Lua API

= Lua API: Global variables =

This page contains a list of global variables and variables supported by the [LuaAPI Lua API].

== Table of Contents ==
<wiki:toc max_depth="3" />

== General variables and constants ==
Here are some unsorted variables or constants which are available in Lua. *Consider these variables to be read-only.*

|| *Identifier* || *Description* ||
|| `LOCALE` || Current locale identifier (e.g. `"de"` for German) ||
|| `INTERFACE` || Type of the game interface: `"desktop"` for desktop, `"touch"` for touchscreen ||
|| `MAX_HOG_HEALTH` || Maximum possible hedgehog health ||
|| `MAX_TURN_TIME` || Maximum possible turn time in milliseconds ||
|| `LAND_WIDTH` || The width of the landscape in pixels. Not available before `onGameStart` ||
|| `LAND_HEIGHT` || The height of the landscape in pixels. Not available before `onGameStart` ||
|| `LeftX` || X coordinate of the leftmost point of the landscape. Not available before `onGameStart` ||
|| `RightX` || X coordinate of the rightmost point of the landscape. Not available before `onGameStart` ||
|| `TopY` || Y coordinate of the topmost point of the landscape. Not available before `onGameStart` ||
|| `CursorX` || The X position of the cursor if the player is choosing a target. Otherwise, this equals `NO_CURSOR` ||
|| `CursorY` || The Y position of the cursor if the player is choosing a target. Otherwise, this equals `NO_CURSOR` ||
|| `NO_CURSOR` || Special value used by `CursorX` and `CursorY` when no cursor is displayed ||
|| `WaterLine` || The y position of the water, used to determine at which position stuff drowns. Use `SetWaterLine` to change. ||
|| `ClansCount` || Number of clans, including defeated ones (a clan is a group of teams with same color) ||
|| `TeamsCount` || Number of teams, including defeated ones ||
|| `TurnTimeLeft` || Number of game ticks (milliseconds) left until the current turn ends. To set this value, use `SetTurnTimeLeft` ||
|| `ReadyTimeLeft` || Remaining ready time in millseconds, 0 if turn in progress. To set this value, use `SetReadyTimeLeft` ||
|| `GameTime` || Number of total game ticks ||
|| `TotalRounds` || Number of rounds that have passed. Equals `-1` if game has not started yet or hogs are still being placed. ||
|| `CurrentHedgehog` || The hedgehog gear that is currently in play ||
|| `AmmoTypeMax` || Maximum ammo type ID (useful to iterate through all ammo types, starting by 0) ||

== !GameFlags ==
The !GameFlags are used to store simple boolean settings of the game.
You can read/modify them using the [LuaGameplay#GameFlags_functions GameFlags functions].

|| *Identifier* || *Description (active state)* ||
|| `gfOneClanMode` || Used when only one clan is in the game. This game flag is primarily used for training missions. ||
|| `gfMultiWeapon` || Shooting any weapon enters multi-shot mode with infinite shots. The remaining shots counter for weapons like shotgun is suppressed. Intended for target practice missions, not recommended for anything else. ||
|| `gfSwitchHog` || Free hog switching at turn start ||
|| `gfDivideTeams` || Each clan will start in its own side of the terrain. No effect if `gfPlaceHog` is active. ||
|| `gfBorder` || An indestructible border is active around the map. ||
|| `gfBottomBorder` || There is an indestructable border at the bottom of the map. ||
|| `gfShoppaBorder` || The terrain edge will be replaced by a decorative black/yellow “danger stripe”. This has no gameplay effect. ||
|| `gfSolidLand` || The terrain is indestructible. ||
|| `gfLowGravity` || The gravity is low. ||
|| `gfLaserSight` || A laser sight is almost always active. ||
|| `gfInvulnerable` || All hedgehogs are invulnerable. ||
|| `gfVampiric` || All hedgehogs become vampires and get 80% of the damage they deal as health. ||
|| `gfKarma` || Attackers share the damage they deal to enemies. ||
|| `gfArtillery` || Hedgehogs can’t walk. ||
|| `gfRandomOrder` || The game is played in random order. ||
|| `gfPlaceHog` || Placement mode: At the beginning of the round, all hedgehogs are placed manually first. ||
|| `gfKing` || King Mode: One hedgehog per team becomes their king, if the king dies, the team loses. ||
|| `gfSharedAmmo` || Teams in the same clan share their ammo. Takes precedence over `gfPerHogAmmo`.  ||
|| `gfDisableGirders` || No girders will be created in random maps ||
|| `gfDisableLandObjects` || No land objects will be created in random maps ||
|| `gfAISurvival` || Computer-controlled hedgehogs will be revived after they die. ||
|| `gfInfAttack` || Attacks don’t end the turn. ||
|| `gfResetWeps` || The weapons will be reset to the initial state each turn. ||
|| `gfPerHogAmmo` || Each hedgehog has its own weapon stash. No effect if `gfSharedAmmo` is active. ||
|| `gfDisableWind` || There is no wind. ||
|| `gfMoreWind` || There is always strong wind. ||
|| `gfTagTeam` || Tag Team: Teams in the same clan share their turn time. ||
|| `gfResetHealth` || The health of all living hedgehogs is reset at the end of each turn. ||

== Game variables ==
The game variables affect several core aspects of gameplay such as map, turn time, etc. They can be set in the `onGameInit` [LuaEvents event].

|| *Identifier* || *Default* || *Description* ||
|| `Theme` || _depends_ || The theme to be used. When `Map` is set, a default value is used. For missions which don't use an image map, `Theme` *must* be set explicitly ||
|| `Map` || `""` || The image map being played or `""` if no image map is used ||
|| `Seed` || `0` || Seed of the random number generator ||
|| `LandDigest` || _N/A_ || Digest for the current map. Only meant for internal use by Hedgewars ||
|| `MapGen` || `mgRandom` || Type of map generator. One of `mgRandom`, `mgMaze`, `mgPerlin`, `mgDrawn`. ||
|| `TemplateNumber` || `0` || Set the number of the land template for the random map generator `mgRandom`. Use this to force a certain “style” of random map. A land template is a rule set for random maps. Maps generated with the same template look similar. You can see the land template number in console when you generate a new random map in the frontend. This field is write-only, you cannot use it to read the template number that Hedgewars chose (you will always get `0`). To be able to set the `TemplateNumber`, you must also set `TemplateFilter` to `6`. ||
|| `TemplateFilter` || `0` || Used for random map generators. This is the number of the template filter to be used. A template filter is a grouping of multiple land templates. This corresponds directly to the map size / map style selection in the frontend (e.g. Small/Medium/Large/Cavern/Wacky). ||
|| `MapFeatureSize` || `50` (`12` in 1.0.0) || Used by random maps to determine its “curvyness” or complexity. This value can be set by the user with the slider under the random map preview in the game setup screen. The user-set value ranges from 1 (leftmost position) to 25 (rightmost position). A good starting value is `12`. ||
|| `GameFlags` || `0` || All `GameFlags` combined as a bitmask. Setting `GameFlags` directly is discouraged, use the [LuaGameplay#GameFlags_functions GameFlags functions] instead ||
|| `Ready` || `5000` || Ready timer at the start of the turn (in milliseconds) ||
|| `Delay` || `100` || Time the current hedgehog needs to be inactive before gear stuff gets updated in infinite attack mode, like applying hog damage and deaths. This is quite an obscure variable, only change it if you know what you're doing ||
|| `TurnTime` || `45000` || Turn time in milliseconds ||
|| `GetAwayTime` || `100` || Retreat time in percent ||
|| `CaseFreq` || `5` || Probability that a crate drops in a turn. 0: never, >0: probability = `1/CaseFreq` ||
|| `MaxCaseDrops` || `5` || Maximum number of crates that can be in the game before the random crate drops stop ||
|| `HealthCaseProb` || `35` || Chance that a crate drop is a health crate, in percent (other crates are ammo or utility crates) ||
|| `HealthCaseAmount` || `25` || Amount of health in a health crate ||
|| `DamagePercent` || `100` || Global damage in percent, affects damage and knockback ||
|| `RopePercent` || `100` || Rope length in percent ||
|| `MinesNum` || `4` || Number of mines being placed on a medium-sized map ||
|| `MinesTime` || `3000` || Time for a mine to explode from activated (in milliseconds), `-1000` for random ||
|| `MineDudPercent` || `0` || Chance of mine being a dud, in percent ||
|| `AirMinesNum` || `0` || Number of air mines being placed on a medium-sized map ||
|| `Explosives` || `2` || Number of barrels being placed on a medium-sized map ||
|| `SuddenDeathTurns` || `15` || Number of rounds until Sudden Death begins, _after the first round is over_. E.g. 0 = SD starts in 2nd round ||
|| `WaterRise` || `47` || Height of water rise in pixels for each Sudden Death turn ||
|| `HealthDecrease` || `5` || Amount of health decreased on each turn in Sudden Death ||
|| `Goals` || `""` || Use this to add additional text to the goal text popup shown at the beginning and when using the quit or pause keys. The text is added to the default text which usually explains the game modifiers and does not replace it. The text supports the same special characters as in `ShowMission` ||
|| `WorldEdge` || `weNone` || Type edges being used at the left and right sides of the terrain (see below). ||
|| `ScreenWidth` || _N/A_ || Width of the Hedgewars window or screen ||
|| `ScreenHeight` || _N/A_ || Height of the Hedgewars window or screen ||

The proper way to disable Sudden Death is by setting both `WaterRise` and `HealthDecrease` to `0`.

== <tt>!TemplateFilter</tt> ==
Depending on the map type (`MapGen`), the meaning of `TemplateFilter` differs:

|| *Template filter number* || *Random maps (`mgRandom`)* || *Perlin maps (`mgPerlin`)* || *Maze maps (`mgMaze`)* ||
|| `0` || All || Small tunnels || Small tunnels ||
|| `1` || Small || Medium tunnels || Medium tunnels ||
|| `2` || Medium || Large tunnels || Large tunnels ||
|| `3` || Large || Small islands || Small islands ||
|| `4` || Cavern || Medium islands || Medium islands ||
|| `5` || Wacky || Large islands || Large islands ||
|| `6` || Will use template specified in `TemplateNumber` || _N/A_ || _N/A_ ||

== <tt>!WorldEdge</tt> ==
The value of `WorldEdge` can have the following values:

|| *Identifier* || *Meaning* ||
|| `weNone` || No world edges ||
|| `weBounce` || Bouncy world edges ||
|| `weWrap` || World wraps around at the edges ||
|| `weSea` || Ocean world edges ||

== Land flags ==
The land flags denote several types of terrain. Like all flags, they can be combined at will.

|| *Identifier* || *Meaning* ||
|| `lfIce` || Slippery terrain, hogs will slide on it. ||
|| `lfBouncy` || Bouncy terrain, hogs and some other gears will bounce off when they collide with it. ||
|| `lfIndestructible` || Almost indestructible terrain, most weapons will not destroy it. ||
|| `0` || Normal destroyable terrain. Note that this is the case when no other land flag is set. ||

== More globals ==
More globals are at at [GearTypes Gear Types], [VisualGearTypes Visual Gear Types], [AmmoTypes Ammo Types], [Sounds], [States], [Sprites].

Note: Some globals are specific to a few functions only and are not mentioned explicitly here; they are instead documented at the corresponding function (example: effect types for the `SetEffect` function).