# HG changeset patch
# User almikes@aol.com
# Date 1417585409 0
# Node ID 70961d4eef051352423b558d6b0cca7801050b70
# Parent  14ec7b5cb5603afd20ca6b9141485c3d932fafbf
Fixed misleading descriptions of GetState and SetState (use of bitmasks were not mentioned). Added commented examples.

diff -r 14ec7b5cb560 -r 70961d4eef05 LuaAPI.wiki
--- a/LuaAPI.wiki	Wed Dec 03 04:53:59 2014 +0000
+++ b/LuaAPI.wiki	Wed Dec 03 05:43:29 2014 +0000
@@ -296,7 +296,7 @@
 
 === <tt>!AddGear(x, y, gearType, state, dx, dy, timer)</tt> ===
 
-<blockquote>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.
+<blockquote>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].
 </blockquote>
 Example:
 
@@ -433,8 +433,34 @@
 </blockquote>
 === <tt>!GetState(gearUid)</tt> ===
 
-<blockquote>returns the state of the gear. This is one of [States]
-</blockquote>
+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:
+<code language="lua">
+local state = GetState(gear)
+--[[ Stores the full raw bitmask of gear in state. Usually
+useless on its own. ]]
+</code>
+
+<code language="lua">
+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.]]
+</code>
+
+<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>
+
+
 === <tt>!GetGearMessage(gearUid)</tt> ===
 
 <blockquote>returns the message of the gear.
@@ -652,8 +678,24 @@
 </blockquote>
 === <tt>!SetState(gearUid, state)</tt> ===
 
-<blockquote>Sets the state of the specified gear to one of [States].
-</blockquote>
+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>
 
 === <tt>!SetGearMessage(gearUid, message)</tt> ===