--- a/LuaAPI.wiki	Tue Aug 21 20:57:56 2018 +0100
+++ b/LuaAPI.wiki	Tue Aug 21 21:03:28 2018 +0100
@@ -404,7 +404,11 @@
     FindPlace(gear, true, 0, LAND_WIDTH)</code>
 
 === <tt>!AddVisualGear(x, y, visualGearType, state, critical [, layer])</tt> ===
-This creates 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.  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. You can set an optional `layer` to specify which visual gears get drawn on top.
+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.
+
+The function returns the `uid` of the visual gear created or `nil` if creation failed.  There is no guarantee the visual gear will actually spawn.  **IMPORTANT: Do not rely on visual gears to spawn**.
+
+Set `critical` to `true` if the visual gear is crucial to gameplay and must always be displayed in-game.  Use `false` if it is just an effect, and its creation be skipped when in fast-forward mode (such as when joining a room).  Most visual gears delete themselves. You can set an optional `layer` to specify which visual gears get drawn on top.
 
 Example: