--- a/LuaAPI.wiki	Mon Aug 03 22:34:06 2015 +0000
+++ b/LuaAPI.wiki	Thu Aug 06 21:54:51 2015 +0000
@@ -48,12 +48,14 @@
 === Color ===
 Some functions take a `color` parameter.
 
-Colors are stored in RGB and are always specified as a three-byte number, where each byte defines a component. The value 0 means no intensity and 255 is largest intensity of the component.
+Colors are stored in RGB or RGBA format and are specified as a three- or four-byte number, respecively.
+In 3-byte (RGB) colors, each byte represents a color component. The value 0 means no intensity and 255 is largest intensity of the component.
 The first byte is for the red component, the second byte for the green component and the third byte for the blue component.
+Four-byte (RGBA) colors use the first 3 bytes for the color components (like for the 3-byte colors) and the fourth byte is used for opacity, where 255 means maximum opacity and 0 means fully transparent (also called the “alpha channel”).
 
 Specifying the color number becomes much easier if you write it in hexadecimal notation.
 
-Examples:
+Examples for RGB (3-byte) colors:
 <code language="lua">
 c = 0x000000 -- black (R, G, B are all 0)
 c = 0xFF0000 -- red
@@ -900,7 +902,7 @@
 Arguments:
 
  * `teamname`: The name of the team.
- * `color`: The color of the team as defined in [LuaAPI#Color]
+ * `color`: The RGB color of the team as defined in [LuaAPI#Color]
  * `grave`: The name of the team’s grave (equals file name without the suffix)
  * `fort`: The name of the team’s fort
  * `voicepack`: The name of the team’s voice pack (equals the directory name)
@@ -918,10 +920,10 @@
 Removes the team with the given team name from the game.
 
 ==== <tt>!GetClanColor(clan)</tt> ====
-Returns the color of the chosen clan by its number. The color data type is described in [LuaAPI#Color].
+Returns the RGB color of the chosen clan by its number. The color data type is described in [LuaAPI#Color].
 
 ==== <tt>!SetClanColor(clan, color)</tt> ====
-Sets the color of the chosen clan by its number. The color data type is described in [LuaAPI#Color].
+Sets the RGB color of the chosen clan by its number. The color data type is described in [LuaAPI#Color].
 
 === Campaign management ===
 ==== <tt>!SaveCampaignVar(varname, value)</tt> ====
@@ -937,8 +939,13 @@
 === <tt>!AddCaption(text)</tt> ===
 Display an event text in the upper part of the screen. The text will be white and the caption group will be `capgrpMessage`.
 
+Example:
+<code language="lua">
+AddCaption("Hello, world!")
+</code>
+
 === <tt>!AddCaption(text, color, captiongroup)</tt> ===
-Display an event text in the upper part of the screen with the specified [LuaAPI#Color color] (4 bytes, the 4th byte is for transparency) and caption group.
+Display an event text in the upper part of the screen with the specified RGBA [LuaAPI#Color color] and caption group. Although an RBGA color is used, Hedgewars does not actually support transparent or semi-transparent captions, so the fourth byte is ignored. We recommend you to always specify a full opacity (`FF` in hexadecimal) for the caption.
 
 || *`captiongroup`* || *Meaning* ||
 || `capgrpGameState` || Used for important global game events, like Sudden Death ||
@@ -948,6 +955,11 @@
 || `capgrpMessage2` || Generic message ||
 || `capgrpAmmostate` || Used to show information about weapon state, i.e. bounce level, timer, remaining shots, etc. ||
 
+Example:
+<code language="lua">
+AddCaption("Melon bomb rain in 2 rounds!", 0xFF0000FF, capgrpGameState)
+-- Green example message.
+</code>
 
 === <tt>!ShowMission(caption, subcaption, text, icon, time)</tt> ===
 Use to tell the player what he is supposed to do.