ALPHA version - expect chaos
LuaAPI
History
API for writing Lua scripts in Hedgewars.
Updated Fri, 17 Nov 2017 04:20:19 +0000 by Wuzzy

Core Lua API documentation

Introduction

Version 0.9.13 of Hedgewars introduced the ability to use Lua scripts to modify Hedgewars behaviour for different maps without having to recompile the whole game. The till then used triggers (only appeared in training maps) were removed.

Lua is an easy to learn scripting language that’s implemented using open source libraries. If you’d like to learn more about Lua, have a look at Lua's official homepage. Even though its easy to learn syntax this wiki page won't explain all basics of using Lua, e.g. declaring variables or using control structures. There are tons of step-by-step tutorials and documentation available on the internet. Just throw “Lua” into your favourite search engine and give it a try.

About this wiki page

This page tends to become outdated. For a list of undocumented functions, see http://hw.ercatec.net/docs/lua_wiki_check.php.

  • Core Lua API documentation
  • Overview

    How Hedgewars handles Lua scripts

    As of Version 0.9.20, Hedgewars supports Lua scripts for two similar tasks: Define tutorial missions, campaign missions or provide special map behaviour for precreated maps. It is also used for multiplayer scripts to create new game styles.

    Tutorial missions

    Tutorial missions are located within text files inside share/hedgewars/Data/Missions/Training . The game will list all files with the lua extension inside this directory in the Training selection screen. You’ll find some premade example scripts within this directory that contain several comments on the script lines and what they do.

    See Missions for details.

    Special maps

    In addition to tutorial missions predrawn maps (maps not created using the random map creator) may contain a single lua script file named map.lua . If it’s there, it will be used once the map is played. This way it’s possible to play maps alone or over the internet using custom goals. Mission maps can be found in singleplayer mode under the “training” button and in multiplayer mode, it is selectable as a map type.

    See also PresetMaps for more information about such maps.

    How Lua scripts are used

    Several parts of script files are executed multiple times. In general, the whole script file is read while loading the map. Declarations as well as function calls outside functions are executed at once. Later on the game will call special predefined function names at special occassions such as the creation of new game objects (called “gears”).

    Important things to know

    It is possible to play missions in multiplayer. However this requires all participating players to have the exact same version of the map files, including the map.lua script file. If this isn’t the case the game will probably desync and “kick” at least the one player using a different version of the map files. To avoid problems when running prepackaged maps, you should never modify any maps provided with the Hedgewars default package. Instead, create a copy of the existing map and modify this one. Feel free to share your work on the forums.

    Another thing to note is the current status of our scripting implementation. Similar to the whole game, this is still work in progress and we can’t guarantee that scripts working in this version will run in future revisions of the game as we might extend, change or rename parts of the scripting engine.

    Global variables/constants

    Global variables are used by the game to interact with the scripts by passing and retrieving their values. While some of the variables are never read by the engine some allow you to modify the engine’s behaviour, e.g. the theme to be used for the current map.

    Functions called by the game: Event handlers

    After successfully loading the Lua script the game will call the following functions on different occasions. To be used, they have to use the exact same name as defined below.

    Data types

    This section defines some commonly used non-primitive parameter types which are used in multiple functions. This section is a bit incomplete at the moment.

    Color

    Some functions take a color parameter.

    Colors are stored in RGB or RGBA format and are specified as a three- or four-byte number, respecively. In 3-byte (RGB) colors, each byte represents a color component. The value 0 means no intensity and 255 is largest intensity of the component. The first byte is for the red component, the second byte for the green component and the third byte for the blue component. Four-byte (RGBA) colors use the first 3 bytes for the color components (like for the 3-byte colors) and the fourth byte is used for opacity, where 255 means maximum opacity and 0 means fully transparent (also called the “alpha channel”).

    Specifying the color number becomes much easier if you write it in hexadecimal notation.

    Examples for RGB (3-byte) colors: c = 0x000000 -- black (R, G, B are all 0) c = 0xFF0000 -- red c = 0x00FF00 -- green c = 0x0000FF -- blue c = 0xFFFFFF -- white c = 0x808080 -- gray (50%)

    Hint: On http://www.colorpicker.com/ you find a color-picking tool for getting RGB colors easily.

    Globally available variables and constants

    The following variables are made available by Hedgewars in Lua and can be used to quickly query a value. Lua scripts schould normally not write to these variables, only read from them.

    General variables and constants

    Here are some unsorted variables or constants which are available in Lua. You shouldn’t write to most of them.

    || AmmoTypeMax || Maximum ammo type ID (useful to iterate through all ammo types, starting by 0)

    Identifier Description
    LAND_WIDTH The width of the landscape in pixels
    LAND_HEIGHT The height of the landscape in pixels
    LeftX X coordinate of the leftmost point of the landscape
    RightX X coordinate of the rightmost point of the landscape
    TopY Y coordinate of the topmost point of the landscape
    CursorX The X position of the cursor if the player is choosing a target. Otherwise, this is -2147483648
    CursorY The Y position of the cursor if the player is choosing a target. Otherwise, this is -2147483648
    WaterLine The y position of the water, used to determine at which position stuff drowns. Use SetWaterLine to change.
    ClansCount Number of clans in the game (teams with the same color belong to one clan)
    TeamsCount Number of teams in the game
    TurnTimeLeft Number of game ticks (milliseconds) left until the current turn ends. You can change this variable directly.
    ReadyTimeLeft Remaining ready time in millseconds, 0 if turn in progress. Can be set in onNewTurn. In other places, it should only be read, not written.
    GameTime Number of total game ticks
    TotalRounds Number of rounds that have passed
    CurrentHedgehog The hedgehog gear that is currently in play

    GameFlags

    The GameFlags are used to store simple boolean settings of the game. You can read/modify them using the 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 TODO (Used in training missions.)
    gfForts Fort Mode
    gfDivideTeams The teams will start at opposite sites of the terrain. Two clans maximum.
    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.
    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.
    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.

    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.
    lfNormal Normal destroyable terrain. Note that this is only actually the case when no other land flag is set.

    More constants

    More constants are at at Gear Types , Ammo Types, Sounds, States, Sprites, Visual Gear Types.

    Event handlers

    Lua scripts are supposed to define these functions to do something. The functions are then called by Hedgewars when a certain event has occoured.

    onGameInit()

    This function is called before the game loads its resources. One can read and modify various game variables here. These variables will become globally available after onGameInit has been invoked, but changing them has only an effect in onGameInit . Most variables are optional, but for missions, Theme must be set by the scripter if you want to use a random map, rather than an image map. All other variables do not need to be set by the scripter and have default values.

    List of game variables:

    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
    MapGen mgRandom Type of map generator. One of mgRandom , mgMaze , mgPerlin , mgDrawn .
    TemplateFilter 0 unknown meaning
    TemplateNumber 0 unknown meaning
    MapFeatureSize 50 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. See LuaAPI#GameFlags_functions for easier manipulation of GameFlags
    Ready 5000 Ready timer at the start of the turn (in milliseconds)
    Delay 100 Delay between each turn in milliseconds
    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
    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 Turns until Sudden Death begins
    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. Use | for line breaks. Also, all text before and including a : in a line will be highlighted. See also 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 .

    If you want to add teams or hogs manually, you have to do it here. If you want to draw your own map using AddPoint and FlushPoints , you have to do this within this function as well.

    WorldEdge

    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

    onGameStart()

    This function is called when the first round starts.

    Can be used to show the mission and for more setup, for example initial target spawning.

    onPreviewInit() (0.9.21)

    This function is called when the map preview in the frontend is initialized. This happens when the script is selected or you change a map generator parameter.

    It is useful for scripts which create their own maps (see AddPoint and FlushPoints ). If you create a map in this function, a preview will be generated from this map and is exposed to the frontend.

    onParameters() (0.9.21)

    This function is called when the script parameters (as specified in the game scheme) become available. The script parameter string is stored in the global variable ScriptParam .

    Please note that it is normally not safe to call many of the other functions inside this function, this function is called very early in the game, only use this to initialize variables and other internal stuff like that.

    Tip: If you use the Params library ( /Scripts/Params.lua ), you can make the task of dissecting the string into useful values a bit easier, but it’s not required. (The Params library is not documented yet, however).

    Tip: If you use this callback, make sure to document the interpretation of the parameters so others know how to set the parameters properly.

    onGameTick()

    This function is called on every game tick, i.e. 1000 times a second. If you just need to check on something periodically, consider onGameTick20 .

    onGameTick20()

    This function is called every 20 game ticks, which equals 50 times a second. It reduces Lua overhead for simple monitoring that doesn’t need to happen every single tick.

    onNewTurn()

    This function calls at the start of every turn. You can set ReadyTimeLeft here to change the ready time for this turn. (See also: Ready )

    onSuddenDeath() (0.9.22)

    This function is called on the start of Sudden Death.

    onGearAdd(gearUid)

    This function is called when a new gear is added. Useful in combination with GetGearType(gearUid) .

    onGearDelete(gearUid)

    This function is called when a new gear is deleted. Useful in combination with GetGearType(gearUid) .

    onVisualGearAdd(vgUid) (0.9.23)

    This function is called when a new visual gear is added. Useful in combination with GetVisualGearType(vgUid) .

    onVisualGearDelete(vgUid) (0.9.23)

    This function is called when a new visual gear is deleted. Useful in combination with GetVisualGearType(vgUid) .

    onGearDamage(gearUid, damage)

    This function is called when a gear is damaged.

    Example:

    function onGearDamage(gear, damage) if (GetGearType(gear) == gtHedgehog) then -- adds a message saying, e.g. "Hoggy H took 25 points of damage" AddCaption(GetHogName(gear) .. ' took ' .. damage .. ' points of damage') end end

    onGearResurrect(gearUid)

    This function is called when a gear is resurrected due to the hog effect heResurrectable being set (see SetEffect ) and/or being an AI hog when the game modifier “AI Survival” ( gfAISurvival ) is active. It is not called when a hog was resurrected by the resurrector tool you can use in the game.

    onAmmoStoreInit()

    This function is called when the game is initialized to request the available ammo and ammo probabilities. Use SetAmmo here.

    onNewAmmoStore(team/clan index, hog index)

    This function is identical to onAmmoStoreInit in function, but is called once per ammo store. This allows different ammo sets for each clan, team or hedgehog depending on the mode. If gfSharedAmmo is set, the parameters passed are the clan index, and -1 , and the function will be called once for each clan. If gfPerHogAmmo is set, the parameters passed are the team index and the hog index in that team, and the function will be called once for each hedgehog. If neither is set, the parameters passed are the team index and -1 , and the function will be called once for each team.

    These indexes can be used to look up details of the clan/team/hedgehog prior to gear creation. Routines to do these lookups will be created as needed. If you add this hook, the expectation is that you will call SetAmmo? appropriately. Any values from onAmmoStoreInit are ignored.

    onGearWaterSkip(gear) (0.9.21)

    This function is called when the gear gear skips over water.

    onScreenResize() (0.9.16)

    This function is called when you resize the screen. Useful place to put a redraw function for any vgtHealthTags you're using.

    onAttack()

    This function is called when your Hedgehog attacks.

    onHJump()

    This function is called when you press the high jump key.

    onLJump()

    This function is called when you press the long jump key.

    onPrecise()

    This function is called when you press the precise key.

    onLeft()

    This function is called when you press the left key.

    onRight()

    This function is called when you press the right key.

    onUp()

    This function is called when you press the up key.

    onDown()

    This function is called when you press the down key.

    onAttackUp()

    This function is called when you release the attack key.

    onDownUp()

    This function is called when you release the down key.

    onHogAttack(ammoType)

    This function is called when you press the attack key. Beginning with 0.9.21, the parameter ammoType is provided. It contains the ammo type of the weapon used for the attack.

    onLeftUp()

    This function is called when you release the left key.

    onPreciseUp()

    This function is called when you release the precise key.

    onRightUp()

    This function is called when you release the right key.

    onSetWeapon(msgParam)

    It is get called when a weapon is selected or switched.

    msgParam tells you which ammo type was selected.

    onSlot(msgParam)

    This function is called when one of the weapon slot keys has been pressed.

    msgParam tells the slot number minus 1 (i.e. 0 is for slot number 1, 1 is for slot number 2, etc.).

    onSwitch()

    This function is called when a hog is switched to another.

    onTaunt(msgParam)

    This function is called when the player uses an animated emote for example by using the chat commands /wave , /juggle , etc.

    msgParam tells you which animation was played:

    msgParam Animation Associated chat command
    0 Rolling up /rollup
    1 Sad face /sad
    2 Waving hand /wave
    3 Stupid winner's grin / “Awesome” face /hurrah
    4 Peeing /ilovelotsoflemonade
    5 Shrug /shrug
    6 Juggling /juggle

    onTimer(msgParam)

    This function is called when one of the timer keys is pressed.

    msgParams tells the set timer in seconds (i.e. 3 for the 3 seconds timer key).

    onUpUp()

    This function is called when you release the up key.

    onUsedAmmo(ammoType) (0.9.23)

    Called after a weapon has been used completely, with ammoType as the used ammo type.

    For example, it is called right after a bazooka is fired, when both shots of a shotgun have been fired, when extra time is used, or when all 4 shots of a portable portal device have been fired. It is also called when using a multi-shot ammo has been aborted by changing the weapon selection mid-way, because this still uses up the ammo.

    onHogHide(gearUid) (0.9.16)

    This function is called when a hedgehog with the gear ID gearUid is hidden (removed from the map).

    onHogRestore(gearUid) (0.9.16)

    This function is called when a hedgehog with the specified gear ID gearUid is restored (unhidden).

    onSpritePlacement(spriteId, centerX, centerY) (0.9.21)

    This function is called when a Sprite has been placed.

    spriteID is the type of the sprite, you find a list at Sprites. centerX and centerY are the coordinates of the center of the sprite.

    onGirderPlacement(frameIdx, centerX, centerY) (0.9.21)

    This function is called when a girder has been placed.

    frameIdx is used for the length and orientation of the girder. The possible values are explained in PlaceGirder . centerX and centerY are the coordinates of the girder’s center.

    onRubberPlacement(frameIdx, centerX, centerY) (0.9.21)

    This function is called when a rubber has been placed.

    frameIdx is used for the rubber orientation. The possible values are explained in PlaceRubber . centerX and centerY are the coordinates of the rubber’s center.

    Functions for creating gears

    AddGear(x, y, gearType, state, dx, dy, timer)

    This creates a new gear at position x,y (measured from top left) of kind gearType (see Gear Types). The initial velocities are dx and dy . All arguments are numbers. The function returns the uid of the gear created. Gears can have multple states at once: state is a bitmask, the flag variables can be found in States.

    Example:

    local gear = AddGear(0, 0, gtTarget, 0, 0, 0, 0) FindPlace(gear, true, 0, LAND_WIDTH)

    AddVisualGear(x, y, visualGearType, state, critical)

    This creates a new visual gear at position x,y (measured from top left) of kind visualGearType (see Visual Gear Types). The function returns the uid of the visual gear created. Set critical to true if the visual gear is crucial to game play. Use false if it is just an effect, and can be skipped when in fast-forward mode (such as when joining a room). A critical visual gear will always be created, a non-critical one may fail. Most visual gears delete themselves.

    Example:

    -- adds an non-critical explosion at position 1000,1000. Returns 0 if it was not created. vgear = AddVisualGear(1000, 1000, vgtExplosion, 0, false)

    SpawnHealthCrate(x, y, [, health])

    Spawns a health crate at the specified position. If x and y are set to 0, the crate will spawn on a random position (but always on land). Set health for the initial health contained in the health crate. If not set, the default health ( HealthCaseAmount ) is used.

    SpawnAmmoCrate(x, y, ammoType [, amount])

    Spawns an ammo crate at the specified position with content of ammoType (see Ammo Types). If ammoType is set to amNothing , a random weapon (out of the available weapons from the weapon scheme) will be selected. If x and y are set to 0, the crate will spawn on a random position (but always on land). The amount parameter specifies the amount of ammo contained in the crate. If amount is nil or 0 , the value set by SetAmmo is used, or if SetAmmo has not been used, it falls back to the weapon scheme's value. If ´amount is equal to or greater than 100` or greater, the amount is infinite.

    Note that in Lua missions, the default number of ammo in crates is 0, so it has to be set to at least 1 with SetAmmo first, see the example:

    Example:

    SetAmmo(amGrenade, 0, 0, 0, 1) -- grenade ammo crates now contain 1 grenade each SpawnAmmoCrate(0, 0, amGrenade) -- spawn grenade ammo crate at random position

    SpawnUtilityCrate(x, y, ammoType [, amount])

    Spawns an utility crate with some ammo at the specified position. The function behaves almost like SpawnAmmoCrate , the differences are 1) the crate looks different and 2) if ammoType is set to amNothing , a random utility out of the set of available utilities from the weapon scheme is chosen as content.

    Example:

    SetAmmo(amLaserSight, 0, 0, 0, 1) SpawnUtilityCrate(0, 0, amLaserSight)

    SpawnFakeAmmoCrate(x, y, explode, poison)

    Spawns a crate at the specified coordinates which looks exactly like a real ammo crate but contains not any ammo. It can be use useful for scripted events or to create a trap. If x and y are set to 0, the crate will spawn on a random position (but always on land). explode and poison are booleans. If explode is true , the crate will explode when collected. If poison is true , the collector will be poisoned.

    Example:

    SpawnFakeAmmoCrate(500, 432, false, false) -- Spawns a fake ammo crate at the coordinates (500, 434) without explosion and poison.

    SpawnFakeHealthCrate(x, y, explode, poison)

    Spawns a crate at the specified coordinates which looks exactly like a real health crate but it will not heal the player. It can be use useful for scripted events or to create a trap. If x and y are set to 0, the crate will spawn on a random position (but always on land). explode and poison are booleans. If explode is true , the crate will explode when collected. If poison is true , the collector will be poisoned.

    SpawnFakeUtilityCrate(x, y, explode, poison)

    Spawns a crate at the specified coordinates which looks exactly like a real utility crate but contains not any ammo. It can be use useful for scripted events or to create a trap. If x and y are set to 0, the crate will spawn on a random position (but always on land). explode and poison are booleans. If explode is true , the crate will explode when collected. If poison is true , the collector will be poisoned.

    AddHog(hogname, botlevel, health, hat)

    Adds a new hedgehog for current team (last created one with the AddTeam function), with bot level and specified health, also hat. botlevel ranges from 0 to 5 , where 0 denotes a human player and 1 to 5 denote the skill level of a bot, where 1 is strongest and 5 is the weakest. Note that this is the reverse order of how the bot level is displayed in the game.

    Warning: This works only for singleplayers training missions for now and will desync multiplayer games.

    Example:

    local player = AddHog("HH 1", 0, 100, "NoHat") -- botlevel 0 means human player SetGearPosition(player, 1500, 1000)

    Functions to get gear properties

    GetGearType(gearUid)

    This function returns the gear type for the specified gear.

    GetVisualGearType(vgUid) (0.9.23)

    This function returns the visual gear type for the specified visual gear.

    GetGearPosition(gearUid)

    Returns x,y coordinates for the specified gear. Not to be confused with GetGearPos .

    GetGearRadius(gearUid)

    Returns the Radius value for the specified gear. For most gear types for “projectile” gears (like gtShell or gtGrenade ), the radius refers to the gear's collision radius. This is an invisible circle around the center of the gear which is used for the collision checks. For a few gear types, its radius means something different, see Types? for a full list.

    To set the Radius value, use SetGearValues .

    GetGearVelocity(gearUid)

    Returns a tuple of dx,dy values for the specified gear.

    GetFlightTime(gearUid)

    Returns the FlightTime of the specified gear. The FlightTime is a gear varialbe used to store a general time interval. The precise meaning of the FlightTime depends on the gear type.

    For example: The FlightTime of a hedgehog ( gtHedgehog ) is the time since they last have stood on solid ground. For most projectile gear types (i.e. gtShell ), it stores the time after it has been launched.

    GetGearElasticity(gearUid)

    Returns the elasticity of the specified gear. The elasticity normally determines how strong the gear will bounce after collisions, where higher elasticity is for stronger bounces.

    This is also useful for determining if a hog is on a rope or not. If a hog is attached to a rope, or is busy firing one, the elasticity of the rope will be non-zero.

    GetGearFriction(gearUid)

    Returns the friction of the specified gear. The friction normally determines how well the gear will slide on terrain. Higher values are for increased sliding properties.

    GetHogClan(gearUid)

    Returns the clan ID of the specified hedgehog gear.

    GetHogTeamName(gearUid)

    Returns the name of the specified gear’s team. gearUid can be a hedgehog or a grave.

    GetHogName(gearUid)

    Returns the name of the specified hedgehog gear.

    GetEffect(gearUid, effect)

    Returns the state of given effect for the given hedgehog gear.

    See SetEffect for further details.

    GetHogHat(gearUid)

    Returns the hat of the specified hedgehog gear.

    GetHogFlag(gearUid) (0.9.22)

    Returns the name of the flag of the team of the specified hedgehog gear.

    GetHogFort(gearUid) (0.9.23)

    Returns the name of the fort of the team of the specified hedgehog gear.

    GetHogGrave(gearUid) (0.9.22)

    Returns the name of the grave of the team of the specified hedgehog gear.

    GetHogVoicepack(gearUid) (0.9.22)

    Returns the name of the voicepack of the team of the specified hedgehog gear.

    GetAmmoCount(gearUid, ammoType) (0.9.16)

    Returns the ammo count of the specified ammo type for the specified hedgehog gear.

    IsHogLocal(gearUid) (0.9.23)

    Returns true if the specified hedgehog gear is controlled by a human player on the computer on which Hedgewars runs on (i.e. not over a computer over the network). Returns false otherwise. Returns nil if gearUid is invalid.

    GetGearTarget(gearUid, x, y) (0.9.16)

    Returns the x and y coordinate of target-based weapons/utilities. Note:: This can’t be used in onGearAdd() but must be called after gear creation.

    GetX(gearUid)

    Returns x coordinate of the gear.

    GetY(gearUid)

    Returns y coordinate of the gear.

    GetState(gearUid)

    Returns the state of the gear. The gear state is a bitmask which is built out of the variables as shown in States.

    This function is usually used in combination with band to extract the truth value of a single flag. It is also used together with SetState and bor in order to activate a single flag.

    Examples: local state = GetState(gear) --[[ Stores the full raw bitmask of gear in state. Usually useless on its own. ]]

    isDrowning = band(GetState(CurrentHedgehog),gstDrowning) ~= 0 --[[ GetState(CurrentHedgehog) returns the state bitmask of CurrentHedgehog, gstDrowning is a bitmask where only the “drowning” bit is set. band does a bitwise AND on both, if it returns a non-zero value, the hedgehog is drowning.]]

    SetState(CurrentHedgehog, bor(GetState(CurrentHedgehog), gstInvisible)) --[[ first the state bitmask of CurrentHedgehog is bitwise ORed with the gstInvisible flag, thus making the bit responsible for invisiblity to become 1. Then the new bitmask is applied to CurrentHedgehog, thus making it invisible.]]

    GetGearMessage(gearUid)

    Returns the message of the gear. This is a bitmask built out of flags seen in GearMessages.

    GetTag(gearUid)

    Returns the tag of the specified gear (by gearUid ).

    The Tag of a gear is just another arbitrary variable to hold the gear's state. The meaning of a tag depends on the gear type. For example, for gtBall gears, it specifies the ball color, for gtAirAttack gears (airplane) it specifies the direction of the plane, etc. See GearTypes for a full list. The returned value will be an integer.

    Note that the word “tag” here does not refer to the name and health tags you see above hedgehogs, this is something different.

    -- This adds a ball (the one from the ballgun) at (123, 456): ball = AddGear(123, 456, gtBall, 0, 0, 0, 0) -- The tag of a ball defines its color. It will automatically chosen at random when created. colorTag = GetTag(ball) -- Now colorTag stores the tag of ball (in this case a number denoting its color)

    The meaning of tags are described in GearTypes.

    GetFollowGear()

    Returns the uid of the gear that is currently being followed.

    GetTimer(gearUid)

    Returns the timer of the gear. This is for example the time it takes for watermelon, mine, etc. to explode. This is also the time used to specify the blowtorch or RC plane time. See GearTypes for a full list.

    GetHealth(gearUid)

    Returns the health of the gear. Depending on the gear type, the gear's “health” can also refer to other things, see GearTypes for a full list.

    GetHogLevel(gearUid)

    Returns the bot level ranging from 0 to 5 . 1 is the strongest bot level and 5 is the weakest one. 0 is for human player.

    GetGearPos(gearUid)

    Get the Pos value of the specified gear. Pos is just another arbitrary value to hold the state of the gear, such as Tag and Health , the meaning depends on the gear type. See GearTypes for the conrete meaning of a gear's Pos value.

    Important: Pos is not related to the gear's position, use GetGearPosition for that.

    GetGearValues(gearUid) (0.9.22)

    This returns a bunch of values associated with the gear, their meaning is often depending on the gear type and many values might be unused for certain gear types.

    This is returned (all variables are integers):

    Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, nImpactSounds, Tint, Damage, Boom

    Boom is 0.9.23+

    A rough description of some of the parameters:

    • Radius : Effect or collision radius, most of the time
    • ImpactSound : Sound it makes on a collision (see Sounds)
    • Tint : Used by some gear types to determine its colorization. The color is in RGBA format.
    • Boom : Used by most gears to determine the damage dealt. (0.9.23+)

    Example: -- Get all values in a single line of code (omit Boom in 0.9.22) : local Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, nImpactSounds, Tint, Damage, Boom = GetGearValues(myGear)

    GetVisualGearValues(vgUid)

    This returns the typically set visual gear values, useful if manipulating things like smoke or bubbles or circles. It returns the following values:

    X, Y, dX, dY, Angle, Frame, FrameTicks, State, Timer, Tint

    • X , Y : typically position
    • dX , dY : typically speed
    • Angle is usually the rotation angle
    • Frame is typically the animation frame
    • FrameTicks is usually an animation counter
    • State can have a variety of values, but is typically bit packed
    • Timer is usually the gear lifetime
    • Tint is the RGBA color

    Most visual gears require little to no modification of parameters.

    Example:

    GetVisualGearValues(vgUid) -- return visual gear values

    Functions to modify gears

    HideHog(gearUid)

    Removes a hedgehog from the map. The hidden hedgehog can be restored with RestoreHog(gearUid) . Since 0.9.23, returns true on success and false on failure (if gear does not exist / hog is already hidden).

    Example:

    gear = AddGear(...) HideHog(gear) -- Hide the newly created gear.

    RestoreHog(gearUid)

    Restores a previously hidden hedgehog.

    Example:

    gear = AddGear(...) HideHog(gear) -- Hide the newly created gear. RestoreHog(gear) -- Restore the newly hidden gear.

    DeleteGear(gearUid)

    Deletes a gear.

    Example:

    gear = AddGear(...) DeleteGear(gear) -- Delete the newly created gear.

    DeleteVisualGear(vgUid)

    Deletes a visual gear. Note, most visual gears delete themselves.

    Example:

    vgear = AddVisualGear(...) DeleteVisualGear(vgear) -- Delete the newly created visual gear.

    SetGearValues(gearUid, Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, ImpactSounds, Tint, Damage, Boom) (0.9.22)

    Sets various gear value for the specified gear ( gearUid ). The meaining of each value often depends on the gear type. See the documentation on GetGearValues for a brief description of the gear values. Boom is 0.9.23+.

    Set nil for each value you do not want to change.

    Example: -- Paints all RC planes into a white color function onGearAdd(gear) if GetGearType(gear) == gtRCPlane then SetGearValues(gear, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, 0xFFFFFFFF) end end

    SetVisualGearValues(vgUid, X, Y, dX, dY, Angle, Frame, FrameTicks, State, Timer, Tint)

    This allows manipulation of many of the visual gear values. In the case of vgtCircle , the visual gear values are mapped as follows:

    • X , Y : Position
    • State : Radius.
    • Timer : Thickness
    • FrameTicks : Pulsation speed ( 0 to disable)
    • dX , dY : min/max pulsation opacity ( 0 - 255 )
    • Tint : RGBA color

    Most visual gears require little to no modification of parameters.

    Example 1:

    -- set a circle to position 1000,1000 pulsing from opacity 20 to 200 (8%-78%), radius of 50, 3px thickness, bright red. SetVisualGearValues(circleUid, 1000,1000, 20, 200, 0, 0, 100, 50, 3, 0xff0000ff)

    Beginning from 0.9.21-dev, the 2nd to 11th arguments are optional. Any such argument which is declared as nil will not overwrite the corresponding value of the visual gear. With this change, it is not required anymore to call GetVisualGearValues beforehand.

    Example 2:

    -- set a circle to position 1000,1000 SetVisualGearValues(circleUid, 1000, 1000) -- set the color of a circle to bright red. SetVisualGearValues(circleUid, nil, nil, nil, nil, nil, nil, nil, nil, nil, 0xff0000ff)

    FindPlace(gearUid, fall, left, right, tryHarder) (0.9.16)

    Finds a place for the specified gear between x= left and x= right and places it there. 0.9.16 adds an optional fifth parameter, tryHarder . Setting to true / false will determine whether the engine attempts to make additional passes, even attempting to place gears on top of each other.

    Example:

    gear = AddGear(...) FindPlace(gear, true, 0, LAND_WIDTH) -- places the gear randomly between 0 and LAND_WIDTH

    HogSay(gearUid, text, manner [,vgState ,vgState])

    Makes the specified gear say, think, or shout some text in a comic-style speech or thought bubble. In 0.9.21 gearUid is not limited to hedgehogs, altough the function name suggests otherwise.

    The manner parameter specifies the type of the bubble and can have one of these values:

    Value of manner Looks
    SAY_THINK Thought bubble
    SAY_SAY Speech bubble
    SAY_SHOUT Exclamatory bubble (denotes shouting)

    As of 0.9.21, there is a optional 4th parameter vgState , it defines wheather the speechbubble is drawn fully opaque or semi-transparent. The value 0 is the default value.

    Value of vgState Effect
    0 If the specified gear is a hedgehog, and it’s the turn of the hedgehog’s team, the bubble is drawn fully opaque.
    If the gear is a hedgehog, and it’s another team’s turn, the bubble is drawn translucent.
    If the gear is not a hedgehog, the bubble is drawn fully opaque.
    1 The bubble is drawn translucent.
    2 The bubble is drawn fully opaque.

    Examples:

    HogSay(CurrentHedgehog, "I wonder what to do …", SAY_THINK) -- thought bubble with text “I wonder what to do …” HogSay(CurrentHedgehog, "I'm hungry.", SAY_SAY) -- speech bubble with text “I’m hungry.” HogSay(CurrentHedgehog, "I smell CAKE!", SAY_SHOUT) -- exclamatory bubble with text “I smell CAKE!”

    HogTurnLeft(gearUid, boolean)

    Faces the specified hog left or right.

    Example:

    HogTurnLeft(CurrentHedgehog, true) -- turns CurrentHedgehog left HogTurnLeft(CurrentHedgehog, false) -- turns CurrentHedgehog right

    SetGearPosition(gearUid, x, y)

    Places the specified gear exactly at the position ( x , y ). Not to be confused with SetGearPos .

    SetGearVelocity(gearUid, dx, dy)

    Gives the specified gear the velocity of dx , dy .

    SetFlightTime(gearUid, flighttime)

    Sets the FlightTime of the given gear to flighttime . The meaning of FlightTime is explained in the section GetFlightTime .

    SetGearElasticity(gearUid, Elasticity)

    Sets the elasticity of the specified gear. For most gears, the elasticity determines how strong the gear will bounce after collisions, where higher elasticity is for stronger bounces. Recommended are values between 0 and 9999 .

    SetGearFriction(gearUid, Friction)

    Sets the friction of the specified gear. The friction normally determines how well the gear will slide on terrain. Higher values are for increased sliding properties. 0 is for no sliding whatsoever, where 9999 is for very long slides, greater values are not recommended.

    SetHealth(gearUid, health)

    Sets the health of the specified gear. The “health” of a gear can refer to many things, depending on the gear type.

    Use cases:

    • Setting the health of a hedgehog ( gtHedgehog ) to 99
    • Starting the RC Plane ( gtRCPlane ) with 10 bombs
    • Starting flying saucer ( gtJetpack ) with only 50% fuel
    • Setting all the mines ( gtMine ) to duds
    • And more!

    See GearTypes for a full description.

    function onGearAdd(gear) if (GetGearType(gear) == gtHedgehog) then -- Set hedgehog health to 99 SetHealth(gear, 99) end if (GetGearType(gear) == gtRCPlaane) then -- Give the plane 10 bombs SetHealth(gear, 10) end if (GetGearType(gear) == gtJetpack) then -- Set fuel to 50% only SetHealth(gear, 1000) end if (GetGearType(gear) == gtMine) then -- Turn mine into dud SetHealth(gear, 0) end end

    SetEffect(gearUid, effect, effectState)

    Sets the state for one of the effects heInvulnerable, heResurrectable, hePoisoned, heResurrected, heFrozen for the specified hedgehog gear. A value of 0 usually means the effect is disabled, values other than that indicate that it is enabled and in some cases specify e.g. the remaining time of that effect.

    effect Description effectState
    heInvulnerable Wether hog is invulnerable Any non-zero value turns on invulnerability. 0 turns it off.
    hePoisoned Poison damage, damages hog each turn. Amount of damage per turn. Use 0 to disable poisoning.
    heResurrectable Whether to resurrect the hog on death With a non-zero value, the hedgehog will be resurrected and teleported to a random location on death. 0 disables this.
    heResurrected Whether the hedgehog has been resurrected once. This is only a subtle graphical effect. With a non-zero value, the hedgehog was resurrected, 0 otherwise.
    heFrozen Freeze level. Frozen hedgehogs skip turn, are heavy and take half damage The number denotes “how frozen” the hedgehog is, i.e. how long it takes to melt. The freezer sets this to 199999 initially. The value will be reduced by 50000 each round. Being hit by a flame reduces this number by 1000 . If 0 , the hedgehog is not frozen. The value will also be used for some other things by the engine, like animation, etc.

    Example (sets all bots poisoned with poison damage of 1):

    function onGearAdd(gear) if (GetGearType(gear) == gtHedgehog) and (GetHogLevel(gear) > 0) then SetEffect(gear, hePoisoned, 1) end end

    Historic note: prior to the ice-gun release, 0.9.19 (commit r10a0a31804f3) effectState was of boolean type ( true = effect enabled, false = effect disabled)

    CopyPV(gearUid, gearUid)

    This sets the position and velocity of the second gear to the first one.

    FollowGear(gearUid)

    Makes the game client follow the specifiec gear.

    SetHogName(gearUid, name)

    Sets the name of the specified hedgehog gear.

    SetHogTeamName(gearUid, name)

    Sets the team name of the specified gear. The gear can be a hedgehog or grave.

    SetWeapon(ammoType)

    Sets the selected weapon of CurrentHedgehog to one of the Ammo Type.

    Example:

    AddAmmo(CurrentHedgehog, amBazooka, 1) -- give the CurrentHedgehog a bazooka SetWeapon(amBazooka) -- select the Bazooka.

    SetNextWeapon() (0.9.21)

    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.

    SetHogHat(gearUid, hat)

    Sets the hat of the specified hedgehog gear.

    SetGearTarget(gearUid, x, y) (0.9.16)

    Sets the x and y coordinate of target-based weapons/utilities. Note: This can’t be used in onGearAdd() but must be called after gear creation.

    SetState(gearUid, state)

    Sets the state of the specified gear to the specified state . This is a bitmask made out of the variables as seen in States.

    This function is often used together with GetState and the bitmask utility functions band and bnot in order to manipulate a single flag.

    Examples: SetState(CurrentHedgehog, bor(GetState(CurrentHedgehog), gstInvisible)) --[[ first the state bitmask of CurrentHedgehog is bitwise ORed with the gstInvisible flag, thus making the bit responsible for invisiblity to become 1. Then the new bitmask is applied to CurrentHedgehog, thus making it invisible. ]]

    SetState(CurrentHedgehog, band(GetState(CurrentHedgehog), bnot(gstInvisible))) --[[ The reverse of the above: This function toggles CurrentHedgehog’s gstInvisible flag off, thus making it visible again. ]]

    SetGearMessage(gearUid, message)

    Sets the gear messages of the specified gear. message is a bitmask built out of flags seen in GearMessages.

    SetTag(gearUid, tag)

    Sets the Tag value of the specified gear (by gearUid ). The Tag value of a gear is simply an extra variable to modify misc. things. The meaning of a tag depends on the gear type. For example, for gtBall gears, it specifies the ball color, for gtAirAttack gears (airplane) it specifies the direction of the plane, etc. See GearTypes for a full list. tag has to be an integer.

    Note that the word “tag” here does not refer to the name and health tags you see above hedgehogs, this is something different.

    -- This adds a ball (the one from the ballgun) at (123, 456): ball = AddGear(123, 456, gtBall, 0, 0, 0, 0) -- This sets the tag of the gear. For gtBall, the tag specified the color. “8” is the color white. SetTag(ball, 8) --

    The meaning of tags are described in GearTypes.

    SetTimer(gearUid, timer)

    Sets the timer of the specified gear. Also see GetTimer .

    SetHogLevel(gearUid, level)

    Sets the bot level from 0 to 5. 0 means human player.

    SetGearPos(gearUid, value) (0.9.18-dev)

    Sets the Pos value (not the position!) of the specified gear to specified value. See GetGearPos for more information.

    Gameplay functions

    GameFlags functions

    ClearGameFlags()

    Disables all GameFlags.

    DisableGameFlags(gameflag, ...)

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

    EnableGameFlags(gameflag, ...)

    Enables the listed GameFlags, without changing the status of other GameFlags.

    GetGameFlag(gameflag)

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

    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()

    Returns the current gravity in percent.

    SetWaterLine(waterline)

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

    SetWind(windSpeed)

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

    SetMaxBuildDistance(distInPx) (0.9.22)

    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.

    EndTurn(noTaunts) (0.9.23)

    Ends the current turn.

    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.

    EndGame()

    Makes the game end.

    Ammo

    SetAmmo(ammoType, count, probability, delay, numberInCrate)

    This updates the settings for a specified Ammo Type as of count available for players, spawn probability, availability delay in turns, and the number available in crates. This is supposed to be used in the onAmmoStoreInit() event handler.

    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!

    Example:

    SetAmmo(amShotgun, 9, 0, 0, 0) -- unlimited amount of shotgun ammo for players SetAmmo(amGrenade, 0, 0, 0, 3) -- crates should contain always three grenade SetAmmo(amSkip, 9, 0, 0, 0) -- enable skip

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

    SetAmmoDelay(ammoType, delay)

    Changes the delay of a specified Ammo Type.

    SetAmmoTexts(ammoType, name, caption, description) (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
    • 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.
    • caption : The second line in the ammo menu (below the title). E.g. “Timed grenade” for amGrenade .
    • description : Description text in ammo menu, below the caption.

    title , caption , description can be nil , in which case they will be reverted to the engine default value. This function returns nil .

    Example: -- 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)

    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.

    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.

    Example: -- 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) (0.9.16)

    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 100 will give infinite ammo.

    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()

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

    TestRectForObstacle(x1, y1, x2, y2, landOnly) (0.9.16)

    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) (0.9.16)

    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 :

    frameIdx Length Orientation
    0 short horizontal
    1 short decreasing right
    2 short vertical
    3 short increasing right
    4 long horizontal
    5 long decreasing right
    6 long vertical
    7 long increasing right

    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 :

    frameIdx Orientation
    0 horizontal
    1 decreasing right
    2 vertical
    3 increasing right

    PlaceSprite(x, y, sprite, frameIdx, tint, behind, flipHoriz, flipVert, [, landFlag, ...])

    Places a 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
    • sprAmRubber
    • sprAMSlot
    • sprAMAmmos
    • sprAMAmmosBW
    • sprAMCorners
    • sprHHTelepMask
    • sprTurnsLeft
    • sprSpeechCorner
    • sprSpeechEdge
    • sprSpeechTail
    • sprTargetBee (since 0.9.23)
    • sprThoughtCorner
    • sprThoughtEdge
    • sprThoughtTail
    • sprShoutCorner
    • sprShoutEdge
    • sprShoutTail
    • sprBotlevels
    • sprIceTexture
    • sprCustom1
    • sprCustom2

    tint is for an RGBA colouring to apply, this works about the same as Tint in gears. behind indicates the sprite should not replace existing land. flipHoriz and flipVert are for mirroring the sprite vertically and horizontally before placing, respectively. The 9th and later arguments specify land flags (see the constants section) to be used for the newly created terrain. If omited, lfNormal is assumed.

    Example:

    PlaceSprite(2836, 634, sprAmGirder, 5) -- Places the girder sprite as normal terrain at (2836, 634). The `frameIdx` 5 is for the long decreasing right girder. 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, ...])

    Erases a 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.

    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.

    Examples:

    EraseSprite(2836, 634, sprAmGirder, 5) -- Removes the girder sprite at (2836, 634). The frameIdx 5 is for the long decreasing right girder. 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] ]) (0.9.21)

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

    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.

    FlushPoints() (0.9.21)

    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

    GetCurAmmoType() (0.9.16)

    Returns the currently selected Ammo Type.

    SwitchHog(gearUid) (0.9.16)

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

    SetInputMask(mask)

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

    Example: -- masks the long and high jump commands SetInputMask(band(0xFFFFFFFF, bnot(gmLJump + gmHJump))) -- clears input mask, allowing player to take actions SetInputMask(0xFFFFFFFF) Note: Using the input mask is an effective way to script uninterrupted cinematics, or create modes such as No Jumping.

    Note: This function is used internally in the Animate library.

    See also GearMessages.

    GetInputMask()

    Returns the current input mask of the player.

    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)

    Adds a new team. Note that this can only be done in onGameInit , not at a later time. You must add at least one hedgehog with AddHog after calling this. The engine does not support empty teams.

    Arguments:

    • teamname : The name of the team.
    • color : The RGB color of the team as defined in LuaAPI#Color
    • grave : The name of the team’s grave (equals file name without the suffix)
    • fort : The name of the team’s fort (equals file name without the suffix and without the letter “L” or “R” before that suffix)
    • 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.

    Note: This works only for singleplayer training missions for now and will desync multiplayer games.

    Example:

    AddTeam("team 1", 0xDD0000, "Simple", "Tank", "Default", "hedgewars") --[[ Adds a new team with name “team 1”, red color (hexadecimal notation), the grave “Simple”, the fort “Tank” the voicepack “Default” and the flag “hedgewars”. ]]

    DismissTeam(teamname)

    Removes the team with the given team name from the game.

    GetClanColor(clan)

    Returns the RGBA color of the chosen clan by its number. The color data type is described in LuaAPI#Color.

    SetClanColor(clan, color)

    Sets the RGBA color of the chosen clan by its number. The color data type is described in LuaAPI#Color.

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

    GetCampaignVar(varname)

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

    Functions affecting the GUI

    AddCaption(text)

    Display an event text in the upper part of the screen. The text will be white and the caption group will be capgrpMessage .

    Example: AddCaption("Hello, world!")

    AddCaption(text, color, captiongroup)

    Display an event text in the upper part of the screen with the specified RGBA color and caption group. Although an RBGA color is used, Hedgewars does not actually support transparent or semi-transparent captions, so the fourth byte is ignored. We recommend you to always specify a full opacity ( FF in hexadecimal) for the caption.

    captiongroup Meaning
    capgrpGameState Used for important global game events, like Sudden Death
    capgrpAmmoinfo Used for new weapon crates and some other events
    capgrpVolume Used when adjusting volume
    capgrpMessage Generic message
    capgrpMessage2 Generic message
    capgrpAmmostate Used to show information about weapon state, i.e. bounce level, timer, remaining shots, etc.

    Example: AddCaption("Melon bomb rain in 2 rounds!", 0xFF0000FF, capgrpGameState) -- Green example message.

    ShowMission(caption, subcaption, text, icon, time)

    This function will open the mission panel and set the texts in it.

    Use to tell the player what he/she is supposed to do. If you use this function, a mission panel is shown for the amount of time specified in time (in milliseconds). If time is set to 0, it will be displayed for a default amount of time. This function replaces the entire text of the mission panel. Compare this to the global Goals variable, which adds to the default text without replacing it.

    caption is the text displayed in the first line, subcaption is displayed in the second line and text is the text displayed in the third and following lines.

    text uses some special characters for formatting: | is used for a line break, and everything written before and including a : in a line is written in a lighter color.

    As of version 0.9.22, icon accepts the following values:

    icon What is shown
    negative number Icon of an ammo type. It is specified as the negative of an ammo type constant (see AmmoTypes), i.e. -amBazooka for the bazooka icon.
    0 Golden crown
    1 Target
    2 Exclamation mark
    3 Question mark
    4 Golden star
    5 Utility crate
    6 Health crate
    7 Ammo crate
    8 Barrel
    9 Dud mine (0.9.23)

    Example: ShowMission(loc("Nobody Laugh"), loc("User Challenge"), loc("Eliminate the enemy before the time runs out"), 0, 0)

    HideMission()

    Hides the mission panel if it is currently displayed, otherwise, this function does nothing.

    SetZoom(zoomLevel)

    Sets the zoom level. The value for maximum zoom is currently 1.0 and for minimum 3.0 The default zoom level is 2.0

    GetZoom()

    Returns the current zoom level.

    SetCinematicMode(enable) (0.9.23)

    Turns on or off cinematic mode. Cinematic mode can be used for cutscenes etc. If enable is set to true , cinematic mode is enabled, if it is false , cinematic mode is disabled.

    Sound functions

    PlaySound(soundId)

    Plays the specified sound. Possible values for soundId are listed on the Sounds page.

    PlaySound(soundId, gearUid)

    Plays the specified sound for the chosen hedgehog gear. This can be used to play a taunt with the voicepack of the hedgehog’s team.

    Possible values for soundId are listed on the Sounds page. See also Taunts.

    File system functions

    HedgewarsScriptLoad(scriptPath)

    Loads a script (i.e. a library) from the specified scriptPath . The root directory is here Hedgewars’ data directory.

    Example: HedgewarsScriptLoad("/Scripts/Locale.lua") -- loads locale library

    GetDataPath()

    Returns the path to the data directory, used when adding libraries.

    GetUserDataPath()

    Returns the path to the user data directory, used when adding libraries.

    Stats functions

    SendStat(TStatInfoType, statMessage[, teamName]) (0.9.20)

    This function allows to change the details of the stats screen seen after the end of a game.

    TStatInfoType is the piece of information you want to manipulate. The result of this functions varies greatly for different TStatInfoType s. The parameter statMessage is mandatory and is a string used for the statistics, its meaning depends on the TStatInfoType . The parameter teamName contains the name of a team which is relevant to the chosen stat. This parameter is not always required, this also depends on TStatInfoType .

    This tables explains the different behaviours of this function for different values of TStatInfoType :

    TStatInfoType Meaning of statMessage Team parameter used?
    siGraphTitle Title of the graph. If you use this, the health icon changes into a star. No
    siGameResult Title of the stats screen, used to show the result of the game, i.e. who won the game No
    siCustomAchievement A freeform text for a single “bullet point” in the “bullet point” list in the details section. For each time you call SendStat with this TStatInfoType , a new “bullet point” gets added to the list. No
    siPointType Replaces the word “kills” in the ranking list. You have to call this each time before you report the score or kills of a team with siPlayerKills . Sadly, grammatical number is currently not respected at all here. No
    siPlayerKills The number of kills for the specified team (converted to a string), as shown in the ranking list. Unless the word “kills” has been replaced by siPointType , then that word is used instead. Only integers (converted to string) are possible. Yes
    siClanHealth Value of a data point (converted to a string). This sets a single data point on the graph for the specified team. Subsequent calls will draw the next point along the horizontal axis; the frontend will then simply connect the dots in the final graph. The graphs are treated independently for each other. Currently the graph only can display positive values. You also should have called SendHealthStatsOff if you use this to prevent the default health graphs to be drawn. Yes
    siMaxStepKills Most hedgehogs killed in a round. statText must be in format “ <kills> <name of killer hedgehog> (<team name of killer>) ”. No
    siMaxTeamDamage Hedgehog with most damage inflicted to his own team. statText must be in the format “ <damage> <hedgehog name> ”. No
    siKilledHHs Total number of killed hedgehogs (converted to string). No
    siTeamStats Sets the ranking of each team. Use number 0 for default ranking. Format: “ <team name 1>:<rank 1>:<team name 2>:<rank 2>: ” (and so on) No
    siMaxStepDamage Best shot award (most damage in one turn). statText must be in format “ <damage> <hedgehog name> (<team name>) ”. No
    siMaxTurnSkips Team with most skips. statText must be of format “ <number> <teamName> ”. No

    Examples:

    -- will automatically change the health icon to a star SendStat(siGraphTitle,'Custom Graph Title') SendStat(siGameResult,'Winner is Team A!') SendStat(siCustomAchievement,'This is a custom message posted in the Details section!') -- Changes the word kill to Point, call it just before sending kills/score for each hog -- in case you want to change the word i.e. print Point or Points SendStat(siPointType,'Point') -- if above function call was not used it will print 3 kills for teamName in Ranking section. -- if it was used it will print 3 Point for teamName in Ranking section. SendStat(siPlayerKills,'3',teamName) -- call siClanHealth to send the "value" of a clan that will be used for the graph creation -- a good idea is to call it always for every hog by using the runOnGears(function) -- in normal mode "value" represents clan health SendStat(siClanHealth, "100",teamName) -- most hedgehogs killed in a round (hedgeHogName is who killed them) SendStat(siMaxStepKills, "1 hedgeHogName (teamName)") -- hog with most damage inflicted to his own team SendStat(siMaxTeamDamage, "100 hedgeHogName") -- total number of killed hedgehogs SendStat(siKilledHHs, "1") -- ranking: sets rank of Megateam to 1 and rank of Superteam to 2 SendStat(siTeamStats, "Megateam:1:Superteam:2:") -- best shot award SendStat(siMaxStepDamage, "30 hedgeHogName (teamName)") -- team with most kills of own hedgehogs SendStat(siMaxStepDamage, "2 teamName") -- team with most skips SendStat(siMaxTurnSkips, "3 teamName")

    Important:

    • As the game engine send stats to the frontend at the end of the game one should send her stats when the game is going to finish and right before the call of EndGame() . (Note: Stats are sent from the engine in CheckForWin . If conditions are met (win or draw) then SendStats(uStats) is called.)
    • Calling just EndGame() won’t produce any stats.
    • If one would like to produce a custom graph see also SendHealthStatsOff() .

    SendHealthStatsOff() (0.9.20)

    Prevents the engine of sending health stats to the frontend.

    If any health stats haven’t been sent before this will cause the health graph to the stats page to be hidden. Use this function in the Lua scripts to produce custom graphs by calling it inside onGameStart() and using the SendStat() function.

    SendAchievementsStatsOff() (0.9.23)

    Prevents the engine of populating the snarky comments in the “Details” section (internally known as “achievements”) of the stats screen, such as “best shot award”, etc. So you can start with a clean list when the game ends normally. This function needs to be called inside onGameStart() .

    SendRankingStatsOff() (0.9.23)

    Prevents the engine of populating the team rankings in the stats screen, so you can start with a clean list when the game ends normally. This function needs to be called inside onGameStart() .

    SendGameResultOff() (0.9.23)

    Prevents the engine of setting the game result text at the top of the stats screen, e.g. “Team 1 wins!” when the game ends normally. This function needs to be called inside onGameStart() .

    GetTeamStats(teamname) (0.9.23)

    Returns a table of internal stats of a team. This table has the following fields:

    * Kills : Number of kills * Suicides : Number of suicides (not yet working) * AIKills : Number of AI kills * TeamKills : Number of hedgehogs killes in own team (excluding current hedghog) * TurnSkips : Number of skipped turns * TeamDamage : Damage inflicted to own team (excluding current hedgehog)

    Math Functions

    div(dividend, divisor)

    Performs an integer division and returns the result. The result is an integer and has the value of the first parameter (an integer) divided by the second parameter (another integer), rounded towards zero.

    band(value1, value2)

    Returns the bitwise logical AND of value1 and value2 .

    bor(value1, value2)

    Returns the bitwise logical OR of value1 and value2 .

    bnot(value)

    Returns the bitwise logical NOT of value .

    Debugging Functions

    WriteLnToConsole(string)

    Writes string to Logs/game0.log , found in the user data directory.

    DumpPoint(x, y) (0.9.23)

    Converts the whole numbers x and y to strings and writes them to Logs/game0.log , one line each.

    ParseCommand(string)

    Makes the game client parse and execute the specified internal game engine command.

    The available commands depend on the current engine protocol version. The engine protocol can (and will) change between releases.

    *Important*: If you use ParseCommand to overcome a shortcoming in our Lua API (e.g. a missing function), please make sure to report the issue.

    With your report we can fix the shortcoming in future releases. We will try to remove the reliance on ParseCommand as good as possible. This will allow scripts to use the previously missing feature in a way that won’t break!

    There are many available commands, but only a few of them are useful for scripting. These are commands used in official scripts in 0.9.22:

    • "skip" : Current hedgehog skips its turn
    • "draw <map>" : Draws a hand-drawn map. MapGen must be mgDrawn for this to work. <map> is a string which must follow the format specified in DrawnMapFormat

    Moreover, the control action names as listed in ConfigurationFiles (under “Binds”) can be used. Note we will eventually try to remove all ParseCommand s in the official scripts.

    EndLuaTest(success)

    This function is used by the Hedgewars developers in testing scripts in order to test the game engine. The testing scripts can be found in the Hedgewars source code under tests/lua . This function is useless for anything else.

    Calling this function ends an engine test and reports a test result.

    success is either one of TEST_SUCCESSFUL to report a successful test or TEST_FAILED for a failed test.

    See EngineTestCases to learn more about testing the engine.