--- a/LuaAPI.wiki Thu Jun 09 12:57:30 2016 +0100
+++ b/LuaAPI.wiki Thu Jun 09 13:47:05 2016 +0100
@@ -439,10 +439,10 @@
== Functions to get gear properties ==
=== <tt>!GetGearType(gearUid)</tt> ===
-This function returns one of [GearTypes Gear Types] for the specified gear.
+This function returns the [GearTypes gear type] for the specified gear.
=== <tt>!GetGearPosition(gearUid)</tt> ===
-Returns x,y coordinates for the specified gear.
+Returns x,y coordinates for the specified gear. Not to be confused with `GetGearPos`.
=== <tt>!GetGearRadius(gearUid)</tt> ===
Returns radius for the specified gear.
@@ -537,7 +537,7 @@
=== <tt>!GetTag(gearUid)</tt> ===
Returns the tag of the specified gear (by `gearUid`).
-A “tag” 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. `tag` has to be an integer.
+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.
@@ -555,16 +555,18 @@
Returns the uid of the gear that is currently being followed.
=== <tt>!GetTimer(gearUid)</tt> ===
-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 rcplane time.
+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.
=== <tt>!GetHealth(gearUid)</tt> ===
-Returns the health of the gear.
+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.
=== <tt>!GetHogLevel(gearUid)</tt> ===
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.
=== <tt>!GetGearPos(gearUid)</tt> ===
-Get pos of specified gear.
+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.
=== <tt>!GetGearValues(gearUid)</tt> (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.
@@ -723,7 +725,7 @@
<code language="lua"> HogTurnLeft(CurrentHedgehog, true) -- turns CurrentHedgehog left
HogTurnLeft(CurrentHedgehog, false) -- turns CurrentHedgehog right</code>
=== <tt>!SetGearPosition(gearUid, x, y)</tt> ===
-Places the specified gear exactly at the position (`x`,`y`).
+Places the specified gear exactly at the position (`x`,`y`). Not to be confused with `SetGearPos`.
=== <tt>!SetGearVelocity(gearUid, dx, dy)</tt> ===
Gives the specified gear the velocity of `dx`, `dy`.
@@ -755,24 +757,33 @@
=== <tt>!SetHealth(gearUid, health)</tt> ===
-Sets the health of the specified gear.
-This can be used for purposes other than killing hedgehogs.
+Sets the health of the specified gear. The “health” of a gear can refer to many things, depending on the gear type.
-For example:
+Use cases:
- * Starting the RC Plane 10 shots
- * Starting Flying Saucer (`gtJetpack`) with only 50% fuel.
- * Setting all the mines to duds.
- * (And more!)
+ * 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>
@@ -857,7 +868,7 @@
Sets the gear messages of the specified gear. `message` is a bitmask built out of flags seen in [GearMessages].
=== <tt>!SetTag(gearUid, tag)</tt> ===
-Sets the tag of the specified gear (by `gearUid`). A “tag” 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. `tag` has to be an integer.
+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.
@@ -871,14 +882,13 @@
The meaning of tags are described in [GearTypes].
=== <tt>!SetTimer(gearUid, timer)</tt> ===
-Sets the timer of the specified gear. Also see `GetTimer`
+Sets the timer of the specified gear. Also see `GetTimer`.
=== <tt>!SetHogLevel(gearUid, level)</tt> ===
Sets the bot level from 0 to 5. `0` means human player.
=== <tt>!SetGearPos(gearUid, value) (0.9.18-dev)</tt> ===
-Set pos of specified gear to specified value.
-
+Sets the `Pos` value (not the position!) of the specified gear to specified value. See `GetGearPos` for more information.
== Gameplay functions ==