Mercurial Mercurial > hwkb / diff
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
LuaAPI.wiki
changeset 1518 1840cbe874bb
parent 1515 ca760c9fcca4
child 1519 1b32e9ff8adf 
--- a/LuaAPI.wiki	Tue Aug 21 23:33:47 2018 +0100
+++ b/LuaAPI.wiki	Tue Aug 21 23:58:55 2018 +0100
@@ -404,16 +404,24 @@
     FindPlace(gear, true, 0, LAND_WIDTH)</code>
 
 === <tt>!AddVisualGear(x, y, visualGearType, state, critical [, layer])</tt> ===
-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.
+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 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).
 
-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**.
+You can set an optional `layer` to specify which visual gears get drawn on top.
+
+Most visual gears delete themselves eventually.
 
-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.
+*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:
 
 <code language="lua">  -- adds an non-critical explosion at position 1000,1000. Returns 0 if it was not created.
-    vgear = AddVisualGear(1000, 1000, vgtExplosion, 0, false) 
+    local vgear = AddVisualGear(1000, 1000, vgtExplosion, 0, false) 
 </code>
 
 === <tt>!SpawnHealthCrate(x, y, [, health])</tt> ===
@@ -648,7 +656,7 @@
 </code>
 
 === <tt>!GetVisualGearValues(vgUid)</tt> ===
-This returns the typically set visual gear values, useful if manipulating things like smoke or bubbles or circles. It returns the following values:
+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`
 
@@ -661,7 +669,7 @@
  * `Timer` is usually the gear lifetime
  * `Tint` is the RGBA color
 
-Most visual gears require little to no modification of parameters.
+Most visual gears require little to no modification of parameters. If the visual gear does not exist, `nil` is returned.
 
 Example:
 
@@ -723,7 +731,7 @@
 </code>
 
 === <tt>!SetVisualGearValues(vgUid, X, Y, dX, dY, Angle, Frame, !FrameTicks, State, Timer, Tint)</tt> ===
-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.
+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:
 
@@ -740,6 +748,8 @@
 
 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:
 
 <code language="lua">  -- set a circle to position 1000,1000 pulsing from opacity 20 to 200 (8%-78%), radius of 50, 3px thickness, bright red.
hwkb