--- a/LuaGears.wiki Wed Apr 17 14:26:35 2019 +0100
+++ b/LuaGears.wiki Wed Apr 17 14:32:17 2019 +0100
@@ -1,23 +1,32 @@
#summary List of gear-related functions in the Lua API
= Lua API: Gear functions =
-This is a list of all functions in the [LuaAPI Lua API] that are related to gears and visual gears. Refer to [LuaGuide] for an introduction into gears.
+This is a list of all functions in the [LuaAPI 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.
<wiki:toc max_depth="3"/>
-== Functions for creating 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 [GearTypes Gear Types]). 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.
-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].
+This creates a new gear at position x,y (measured from top left) of kind `gearType` (see [GearTypes 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:
-<code language="lua"> local gear = AddGear(0, 0, gtTarget, 0, 0, 0, 0)
+<code language="lua"> -- 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)</code>
=== `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 [VisualGearTypes Visual Gear Types]). 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.
+This attempts to create a new visual gear at position x,y (measured from top left) of kind `visualGearType` (see [VisualGearTypes 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`.
@@ -115,7 +124,37 @@
=== `SpawnFakeUtilityCrate(x, y, explode, poison) ` ===
Same as `SpawnFakeAmmoCrate`, except the crate will look like an utility crate.
-== Functions to get gear properties ==
+== 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(gearUid, gearUid)` ===
+This sets the position and velocity of the second gear to the first one.
+
+=== `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:
+
+<code language="lua"> gear = AddGear(...)
+ FindPlace(gear, true, 0, LAND_WIDTH) -- places the gear randomly between 0 and LAND_WIDTH</code>
+
+== General gear properties ==
=== `GetGearType(gearUid)` ===
This function returns the [GearTypes gear type] for the specified gear, if it exists. If it doesn't exist, `nil` is returned.
@@ -123,90 +162,6 @@
=== `GetVisualGearType(vgUid)` (0.9.23) ===
This function returns the [VisualGearTypes visual gear type] for the specified visual gear, if it exists. If it doesn't exist, `nil` is returned.
-=== `GetGearPosition(gearUid)` ===
-Returns x,y coordinates for the specified gear. Not to be confused with `GetGearPos`.
-
-=== `GetGearCollisionMask(gearUid)` ===
-Returns the current collision mask of the given gear. See `SetGearCollisionMask` for an explanation of the mask.
-
-=== `GetGearRadius(gearUid)` ===
-Returns the `Radius` value for the specified gear. For most [GearTypes 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`.
-
-=== `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 a non-zero number.
-
-=== `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.
-
-=== `IsHogHidden(gearUid)` (0.9.25) ===
-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.
-
-=== `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)` ===
-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)` ===
-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)` (0.9.25) ===
-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:
-<code lang="lua">GetAmmoTimer(CurrentHedgehog, amGrenade)
--- May return 1000, 2000, 3000, 4000 or 5000</code>
-
-=== `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). Also returns `true` if the hog is a member of any of the local clans. Returns `false` otherwise. Returns `nil` if `gearUid` is invalid.
-
-This is perfect to hide certain captions like weapon messages from enemy eyes.
-
-=== `GetGearTarget(gearUid, x, y) ` ===
-Returns the x and y coordinate of target-based weapons/utilities.
-<b>Note:</b>: 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].
@@ -235,10 +190,33 @@
CurrentHedgehog, thus making it invisible.]]
</code>
+=== `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:
+<code language="lua">
+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. ]]
+</code>
+
+<code language="lua">
+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. ]]
+</code>
+
=== `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`).
@@ -256,23 +234,142 @@
The meaning of tags are described in [GearTypes].
-=== `GetFollowGear()` ===
-Returns the uid of the gear that is currently being followed.
+=== `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.
+
+<code language="lua">
+-- 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) --
+</code>
+
+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.
-=== `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.
+=== `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.
+
+<code language="lua"> 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</code>
+
=== `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:
+<code language="lua">SetGearCollisionMask(gear, bnot(lfCurHogCrate))
+-- Ignore collision with current hedgehog</code>
+
+<code language="lua">SetGearCollisionMask(gear, 0xFFFF)
+-- Collide with everything</code>
+
+<code language="lua">SetGearCollisionMask(gear, lfAllObjMask)
+-- Collide with hedgehogs and objects</code>
+
+<code language="lua">SetGearCollisionMask(gear, 0x0000)
+-- Collide with nothing</code>
+
+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 [GearTypes 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.
+<b>Note:</b>: 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.
@@ -293,6 +390,21 @@
local Angle, Power, WDTimer, Radius, Density, Karma, DirAngle, AdvBounce, ImpactSound, nImpactSounds, Tint, Damage, Boom, Scale = GetGearValues(myGear)
</code>
+=== `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:
+<code language="lua">
+-- 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
+</code>
+
=== `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:
@@ -310,40 +422,6 @@
local X, Y, dX, dY, Angle, Frame, FrameTicks, State, Timer, Tint, Scale = GetVisualGearValues(vgUid)
</code>
-== Functions to change position and velocity ==
-=== `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`.
-
-=== `CopyPV(gearUid, gearUid)` ===
-This sets the position and velocity of the second gear to the first one.
-
-=== `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:
-
-<code language="lua"> gear = AddGear(...)
- FindPlace(gear, true, 0, LAND_WIDTH) -- places the gear randomly between 0 and LAND_WIDTH</code>
-
-== Functions to modify gears ==
-=== `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:
-<code language="lua">
--- 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
-</code>
-
=== `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.
@@ -378,90 +456,47 @@
SetVisualGearValues(circleUid, 1000, 1000)</code>
<code language="lua"> -- set the tint of a visual gear to bright red.
SetVisualGearValues(circleUid, nil, nil, nil, nil, nil, nil, nil, nil, nil, 0xff0000ff)</code>
-
-=== `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:
+
+=== `SetGearAIHints(gearUid, aiHint)` ===
+Set some behaviour hints for computer-controlled hedgehogs for any given gear with `gearUid`.
-|| *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 ||
+Set `aiHint` to either of:
-Beware, the collision mask is often set by the engine as well.
-
-Examples:
-<code language="lua">SetGearCollisionMask(gear, bnot(lfCurHogCrate))
--- Ignore collision with current hedgehog</code>
+ * `aihUsualProcessing`: AI hogs treat this gear the usual way. This is the default.
+ * `aihDoesntMatter`: AI hogs don't bother attacking this gear intentionally.
-<code language="lua">SetGearCollisionMask(gear, 0xFFFF)
--- Collide with everything</code>
-
-<code language="lua">SetGearCollisionMask(gear, lfAllObjMask)
--- Collide with hedgehogs and objects</code>
-
-<code language="lua">SetGearCollisionMask(gear, 0x0000)
--- Collide with nothing</code>
-
-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):
+Example:
-[https://hg.hedgewars.org/hedgewars/file/default/hedgewars/uConsts.pas#l112]
-
-=== `SetFlightTime(gearUid, flighttime)` ===
-Sets the `FlightTime` of the given gear to `flighttime`. The meaning of `FlightTime` is explained in the section `GetFlightTime`.
+<code language="lua">
+SetGearAIHints(uselessHog, aihDoesntMatter)
+-- This makes AI hogs stop caring about attacking uselessHog</code>
-=== `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.
+== Hedgehog-specific gear properties ==
+=== `GetHogName(gearUid)` ===
+Returns the name of the specified hedgehog gear.
-=== `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:
+=== `SetHogName(gearUid, name)` ===
+Sets the name of the specified hedgehog gear.
- * 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!
+=== `GetHogTeamName(gearUid)` ===
+Returns the name of the specified gear’s team. `gearUid` can be a hedgehog or a grave.
-See [GearTypes] for a full description.
+=== `SetHogTeamName(gearUid, name)` ===
+Sets the team name of the specified gear. The gear can be a hedgehog or grave.
-<code language="lua"> 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</code>
+=== `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.
-=== `HealHog(gearUid, healthBoost[, showMessage[, tint]])` (0.9.24) ===
-Convenience function to increase the health of a hedgehog with default visual effects.
+=== `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.
-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.
+=== `GetEffect(gearUid, effect)` ===
+Returns the state of given effect for the given hedgehog gear.
-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`).
+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.
@@ -483,15 +518,43 @@
end
end</code>
-=== `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.
+=== `GetHogHat(gearUid)` ===
+Returns the hat of the specified hedgehog gear.
=== `SetHogHat(gearUid, hat)` ===
Sets the hat of the specified hedgehog gear.
+=== `GetHogFlag(gearUid)` ===
+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)` ===
+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)` (0.9.25) ===
+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:
+<code lang="lua">GetAmmoTimer(CurrentHedgehog, amGrenade)
+-- May return 1000, 2000, 3000, 4000 or 5000</code>
+
+=== `HealHog(gearUid, healthBoost[, showMessage[, tint]])` (0.9.24) ===
+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.
@@ -500,69 +563,8 @@
<code language="lua"> HogTurnLeft(CurrentHedgehog, true) -- turns CurrentHedgehog left
HogTurnLeft(CurrentHedgehog, false) -- turns CurrentHedgehog right</code>
-=== `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.
-
-=== `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:
-<code language="lua">
-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. ]]
-</code>
-
-<code language="lua">
-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. ]]
-</code>
-
-=== `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.
-
-<code language="lua">
--- 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) --
-</code>
-
-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. `1` is the strongest bot level and `5` is the weakest one (this is the reverse of what players see). `0` means human player.
-
-=== `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.
-
-Example:
-
-<code language="lua">
-SetGearAIHints(uselessHog, aihDoesntMatter)
--- This makes AI hogs stop caring about attacking uselessHog</code>
-
-=== `SetGearPos(gearUid, value)` ===
-Sets the `Pos` value (not the position!) of the specified gear to specified value. See `GetGearPos` for more information.
+=== `IsHogHidden(gearUid)` (0.9.25) ===
+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)`. Since 0.9.23, returns `true` on success and `false` on failure (if gear does not exist / hog is already hidden).
@@ -581,7 +583,18 @@
HideHog(gear) -- Hide the newly created gear.
RestoreHog(gear) -- Restore the newly hidden gear.</code>
-== Functions for gear actions ==
+=== `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). Also returns `true` if the hog is a member of any of the local clans. Returns `false` otherwise. 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.
@@ -605,10 +618,7 @@
<code language="lua">HogSay(CurrentHedgehog, "I'm hungry.", SAY_SAY) -- speech bubble with text “I’m hungry.”</code>
<code language="lua">HogSay(CurrentHedgehog, "I smell CAKE!", SAY_SHOUT) -- exclamatory bubble with text “I smell CAKE!”</code>
-=== `FollowGear(gearUid)` ===
-Makes the game client follow the specifiec gear (if it exists). Does not work for visual gears.
-
-== Functions to delete gears ==
+== Deletion ==
=== `DeleteGear(gearUid)` ===
Deletes a gear. If the specified gear did not exist, nothing happens.