Back to homepage
LuaGears
History
List of gear-related functions in the Lua API
LuaFunctions
Updated Thu, 25 May 2023 13:05:48 +0000 by Wuzzy

Lua API: Gear functions

This is a list of all functions in the Lua API that are related to gears and visual gears.

Gears are dynamic objects or events in the world that affect the gameplay, including hedgehogs, projectiles, weapons, land objects, active utilities and a few more esoteric things. Visual gears are decorational objects which are usually used for purely decorational graphical effects. They have no effect on gameplay. Visual gears are not the same as gears, but they share some similarities.

Refer to LuaGuide for a more detailed introduction into gears.

Creation

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. timer is the initial timer value of the gear. If a particular gear value does not matter, use 0 .

Position, velocity, state and timer can be changed afterwards with the various setter functions.

Note: If you want to create a hedgehog ( gtHedgehog ), you must call AddHog or AddMissionHog instead. If you want to spawn a crate ( gtCase ), you must call one of the several “Spawn*Crate” functions (e.g. SpawnSupplyCrate ) below instead.

Example:

-- Spawn a target at (0,0) and place it randomly local gear = AddGear(0, 0, gtTarget, 0, 0, 0, 0) -- also use 0 for velocity. Also 0 for state and timer because they don't matter. FindPlace(gear, true, 0, LAND_WIDTH)

AddVisualGear(x, y, visualGearType, state, critical [, layer])

This attempts to create 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 or nil if creation failed. There is no guarantee that a visual gear will spawn. IMPORTANT: Do not rely on visual gears to spawn. Always be prepared for this function to return nil .

Set critical to true if the visual gear is crucial to gameplay and must always be spawned when in-game. Use false if it is just an effect or eye-candy, and its creation can be skipped when in fast-forward mode (such as when joining a room).

You can set an optional layer to specify which visual gears get drawn on top.

Most visual gears delete themselves eventually.

NOTE: Visual gears must only be used for decorational/informational/rendering purposes. Never use the visual gear's internal state to manipulate anything gameplay-related. Visual gears are not safe for reliable storage and using them as that would lead to strange bugs.

NOTE: Since 0.9.25, visual gears will never spawn when Hedgewars is run in a testing mode (i.e. not as the real game), so don't rely for visual gears to spawn even if they're critical.

Example:

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

AddHog(hogname, botlevel, health, hat)

Adds a new hedgehog for current team (last created one with the AddTeam function), with a bot level, an initial health and a 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. Note that mixing human-controlled and computer-controlled hedgehogs in the same team is not permitted, but it is permitted to use different computer difficulty levels in the same team.

Returns the gear ID.

Warning: This only works in singleplayer mode (e.g. missions). Also, Hedgewars only supports up to 64 hedgehogs in a game.

Example:

local player = AddHog("HH 1", 0, 100, "NoHat") -- botlevel 0 means human player SetGearPosition(player, 1500, 1000) -- hint: If you don't call `SetGearPosition`, the hog spawns randomly

AddMissionHog(health)

Add a hedgehog for the current team, using the player-chosen team identity when playing in singleplayer missions. The “current team” is the last team that was added with AddMissionTeam or AddTeam .

The name and hat match the player's team definition. The hog is also always player-controlled.

Examples: -- Add player team with 3 hogs AddMissionTeam(-1) AddMissionHog(100) AddMissionHog(100) AddMissionHog(100)

-- You can also mix mission hogs with “hardcoded” hogs. -- This adds a player team with 2 hogs taken from the player team and 1 hog with a hardcoded name, botlevel and hat. AddMissionTeam(-2) AddMissionHog(100) AddMissionHog(100) AddHog("My Hardcoded Hog", 0, 100, "NoHat")

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. Do not use a negative value for health .

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

Spawns an ammo or utility crate at the specified position with the given ammo type and an optional amount (default: 1). The crate type is chosen automatically based on the ammo type. Otherwise, this function behaves like SpawnAmmoCrate .

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

Spawns an ammo crate at the specified position with content of ammoType (see Ammo Types). Any ammoType is permitted, an ammo crate is spawned even if the ammo is normally defined as an utility. 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 AMMO_INFINITE , 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. They are optional since 1.0.0 but mandatory until 0.9.25.

If explode is true , the crate will explode when collected (default: false ). If poison is true , the collector will be poisoned (default: false ).

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

Same as SpawnFakeAmmoCrate , except the crate will look like a health crate.

SpawnFakeUtilityCrate(x, y [, explode [, poison]])

Same as SpawnFakeAmmoCrate , except the crate will look like an utility crate.

Position and velocity

GetGearPosition(gearUid)

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

GetX(gearUid)

Returns x coordinate of the gear.

GetY(gearUid)

Returns y coordinate of the gear.

SetGearPosition(gearUid, x, y)

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

GetGearVelocity(gearUid)

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

SetGearVelocity(gearUid, dx, dy)

Gives the specified gear the velocity of dx , dy .

CopyPV(fromGearUid, toGearUid)

When given two gears as arguments, this sets the position and velocity of toGearUid to the position and velocity of fromGearUid .

FindPlace(gearUid, fall, left, right[, tryHarder])

Finds a place for the specified gear between x= left and x= right and places it there. tryHarder is optional, setting it 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

General gear properties

GetGearType(gearUid)

This function returns the gear type for the specified gear, if it exists. If it doesn't exist, nil is returned.

GetVisualGearType(vgUid)

This function returns the visual gear type for the specified visual gear, if it exists. If it doesn't exist, nil is returned.

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

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

GetGearMessage(gearUid)

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

SetGearMessage(gearUid, message)

Sets the gear messages of the specified gear. message 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.

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.

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.

SetTimer(gearUid, timer)

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

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.

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.

Hint: If you like to increase the health of a hedgehog with nice visual effects, consider using HealHog instead.

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

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.

SetGearPos(gearUid, value)

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

GetGearCollisionMask(gearUid)

Returns the current collision mask of the given gear. See SetGearCollisionMask for an explanation of the mask.

SetGearCollisionMask(gearUid, mask)

Set the collision mask of the given gear with gearUid . The collision mask defines with which gears and terrain types the gear can collide.

mask is a number between 0x0000 and 0xFFFF and used as a bitfield, which means you can combine these flags with bor . These are the available flags:

Identifier Collision with …
lfLandMask Terrain
lfCurHogCrate Current hedgehog, and crates
lfHHMask Any hedgehogs
lfNotHHObjMask Objects, not hogs (e.g. mines, explosives)
lfAllObjMask Hedgehogs and objects

Beware, the collision mask is often set by the engine as well.

Examples: SetGearCollisionMask(gear, bnot(lfCurHogCrate)) -- Ignore collision with current hedgehog

SetGearCollisionMask(gear, 0xFFFF) -- Collide with everything

SetGearCollisionMask(gear, lfAllObjMask) -- Collide with hedgehogs and objects

SetGearCollisionMask(gear, 0x0000) -- Collide with nothing

There are actual more flags availbable, but they are not as useful for use in Lua and their constants have not been exposed to Lua. You can find the full range of flags in the engine source code (in Pascal):

https://hg.hedgewars.org/hedgewars/file/default/hedgewars/uConsts.pas#l112

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 GearTypes for a full list.

To set the Radius value, use SetGearValues .

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.

SetFlightTime(gearUid, flighttime)

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

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 a non-zero number.

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 .

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.

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.

GetGearTarget(gearUid, x, y)

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.

SetGearTarget(gearUid, x, y)

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.

GetGearValues(gearUid)

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

That the concrete meaning of each of this variables depends on the gear type and can vary wildly. For most gear types, many of these variables are unused and have no effect.

Here's an overview of the purpose of these variables:

  • Angle : Angle the gear was launched in (usually)
  • Power : Power the gear was launched in (usually)
  • WDTimer : An alternative timer variable, used by some more complex gears like air mines
  • Radius : Effect or collision radius, most of the time
  • Density : A high density makes the gear less prone to being pushed by forces, like explosions, wind and stuff. Gears with a higher density also make a larger splash
  • Karma : Used to track karma damage for hedgehogs in the Karma game modifier, but abused for different purposes for other gears, too
  • DirAngle : ???
  • AdvBounce : ???
  • ImpactSound : Sound it makes on a collision (see Sounds)
  • nImpactSounds : Must be used together with ImpactSound . Number of different impact sounds to use. 0 : Disable impact sound. 1 : Use sound selected in ImpactSound . 2 or higher: Uses a random impact sound each impact. The first possible sound is ImpactSound , the second possible sound is ImpactSound+1 , and so on. The order of sounds is specified at https://hg.hedgewars.org/hedgewars/file/default/hedgewars/uTypes.pas#l120. For example, if ImpactSound is sndHellishImpact1 and nImpactSounds equals 4, the impact sounds will be sndHellishImpact1 to sndHellishImpact4
  • Tint : Colorization of gear. The color is in RGBA format. Not supported by all gears.
  • Damage : Amount of damage taken by gear. Only used by a few gears.
  • Boom : Used by most gears to determine the potential damage / explosion size

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

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

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. If gearUid is invalid or the gear does not exist, nothing happens.

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

GetVisualGearValues(vgUid)

This returns the typically set visual gear values for the specified visual gear vgUid , useful if manipulating things like smoke, bubbles or circles. On success, it returns the following values:

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

The meaning of these values is the same as in SetVisualGearValues .

If the visual gear does not exist, nil is returned. Always check the result for nil before you plug in the values anywhere.

Most visual gears require little to no modification of parameters.

Example:

-- Return visual gear values local X, Y, dX, dY, Angle, Frame, FrameTicks, State, Timer, Tint, Scale = GetVisualGearValues(vgUid)

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

This allows manipulation of the internal state of the visual gear vgUid . If vgUid is invalid or the vgUid does not refer to an existing visual gear, the function does nothing. Thus, you can safely call this function even if you are not sure if the visual gear actually exists.

All visual gear values are numbers. Each visual gear may be using these parameters differently, but the usual meaning of these is the following:

  • X , Y : Position
  • dX , dY : Speed along the X and Y axis
  • Angle : Current rotation
  • Frame : Image frame, if using a sprite sheet
  • FrameTicks is usually an animation counter
  • State : Helper value to save some internal state
  • Timer : Time in milliseconds until it expires
  • Tint : RGBA color
  • Scale is a scale factor (not used by all visual gears)

Some visual gears interpret these values differently, just like normal gears. See VisualGearTypes for details. Also, most visual gears are not using all possible values, while some values are just ignored.

Note that most visual gears require little to no modification of their values.

NOTE: Never use the visual gear's internal state to manipulate/store anything gameplay-related. Visual gears are not safe for reliable storage and using them as that would lead to strange bugs.

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)

Only the first argument is required. Everything else is optional. Any such argument which is declared as nil will not overwrite the corresponding value of the visual gear.

Example 2:

-- set a visual gear to position 1000,1000 SetVisualGearValues(circleUid, 1000, 1000) -- set the tint of a visual gear to bright red. SetVisualGearValues(circleUid, nil, nil, nil, nil, nil, nil, nil, nil, nil, 0xff0000ff)

SetGearAIHints(gearUid, aiHint)

Set some behaviour hints for computer-controlled hedgehogs for any given gear with gearUid .

Set aiHint to either of:

  • aihUsualProcessing : AI hogs treat this gear the usual way. This is the default.
  • aihDoesntMatter : AI hogs don't bother attacking this gear intentionally, or don't bother collecting it if it's a crate

Example:

SetGearAIHints(uselessHog, aihDoesntMatter) -- This makes AI hogs stop caring about attacking uselessHog

Hedgehog-specific gear properties

IsHogAlive(gearUid)

Returns true if specified gear is a hedgehog, alive, not about to die and not hidden. Returns false otherwise.

GetHogName(gearUid)

Returns the name of the specified hedgehog gear.

SetHogName(gearUid, name)

Sets the name of the specified hedgehog gear.

GetHogTeamName(gearUid)

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

SetHogTeamName(gearUid, name)

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

GetHogClan(gearUid)

Returns the clan ID of the specified hedgehog gear.

GetHogLevel(gearUid)

Returns the bot level ranging from 0 to 5 . 1 is the strongest bot level and 5 is the weakest one (this is the reverse of what players see). 0 is for human player.

SetHogLevel(gearUid, level)

Sets the bot level from 0 to 5. 1 is the strongest bot level and 5 is the weakest one (this is the reverse of what players see). 0 means human player.

GetEffect(gearUid, effect)

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

See SetEffect for further details.

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 safe location on death. Resurrection may fail and the hedgehog can still die when there is no or very, very little land left. 0 disables this.
heResurrected Whether the hedgehog has been resurrected by the Resurrector utility (resurrection by heResurrectable does not count). 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 hog is considered frozen if the value is 256 or higher, otherwise not. A number of 256 or higher 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 . The values 0 to 255 are used for the freeze/melt animations.
heArtillery If enabled, the hedgehog can't walk. 0 = disabled. 1 = permanently enabled. 2 = temporarily enabled (used by sniper rifle between shots)

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

GetHogHat(gearUid)

Returns the hat of the specified hedgehog gear.

SetHogHat(gearUid, hat)

Sets the hat of the specified hedgehog gear. hat is the hat name, which equals the file name (case-sensitively) without the file name suffix. If the hat file can not be found on the local computer, the hog will wear no hat.

GetHogFlag(gearUid)

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

GetHogFort(gearUid)

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

GetHogGrave(gearUid)

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

GetHogVoicepack(gearUid)

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

GetAmmoCount(gearUid, ammoType)

Returns the ammo count of the specified ammo type for the specified hedgehog gear. If infinite, returns AMMO_INFINITE .

GetAmmoTimer(gearUid, ammoType)

Returns the currently configured ammo timer (in milliseconds) for the given hedgehog gear and specified ammo type. This is the timer which is set by the player by using the timer keys (1-5). For ammo types for which the timer cannot be changed, nil is returned.

Example: GetAmmoTimer(CurrentHedgehog, amGrenade) -- May return 1000, 2000, 3000, 4000 or 5000

HealHog(gearUid, healthBoost[, showMessage[, tint]])

Convenience function to increase the health of a hedgehog with default visual effects.

Specifically, this increases the health of the hedgehog gear with the given ID gearUid by healthBoost , displays some healing particles at the hedgehog and shows the health increae as a message. This is similar to the behavour after taking a health crate, or getting a health boost from vampirism.

If showMessage is false, no message is shown. With tint you can set the RGBA color of the particles (default: 0x00FF00FF ).

This function does not affect the poison state, however (see SetEffect ).

HogTurnLeft(gearUid, boolean)

Faces the specified hog left or right.

Example:

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

IsHogHidden(gearUid)

Returns true if hedgehog gear is hidden (e.g. via HideHog or the TimeBox), false if it isn't, nil if that hedgehog never existed.

HideHog(gearUid)

Removes a hedgehog from the map. The hidden hedgehog can be restored with RestoreHog(gearUid) . Returns true on success and false on failure (if gear does not exist / hog is already hidden). You must not hide all hogs at once.

Example:

local gear = AddHog(...) HideHog(gear) -- Hide the newly created gear.

RestoreHog(gearUid)

Restores a previously hidden hedgehog. Nothing happens if the hedgehog does not exist or is not hidden.

Example:

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

IsHogLocal(gearUid)

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). Also returns true if the hog is a member of any of the local clans. Returns false otherwise.

If the game has a mission team (see AddMissionTeam ), this function behaves a little different: It only may return true for hogs in the same clan as the mission team and always returns false for hogs from other clans.

Returns nil if gearUid is invalid.

This is perfect to hide certain captions like weapon messages from enemy eyes.

Special gear actions

GetFollowGear()

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

FollowGear(gearUid)

Makes the game client follow the specifiec gear (if it exists). Does not work for visual gears.

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

Makes the specified gear say, think, or shout some text in a comic-style speech or thought bubble. 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)

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

Deletion

DeleteGear(gearUid)

Deletes a gear. If the specified gear did not exist, nothing happens.

Example:

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

DeleteVisualGear(vgUid)

Deletes a visual gear. If it does not exist, nothing happens.

Note, most visual gears delete themselves after a while.

Example:

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