APIDump: Added cLineBlockTracer documentation.

MCServer/Plugins/APIDump/APIDesc.lua

@@ -1168,11 +1168,93 @@ These ItemGrids are available in the API and can be manipulated by the plugins,
 
 		cLineBlockTracer =
 		{
-			Desc = "",
-			Functions = {},
-			Constants = {},
+			Desc = [[Objects of this class provide an easy-to-use interface to tracing lines through individual
+blocks in the world. It will call the provided callbacks according to what events it encounters along the
+way.</p>
+<p>
+For the Lua API, there's only one function exported that takes all the parameters necessary to do the
+tracing. The Callbacks parameter is a table containing all the functions that will be called upon the
+various events. See below for further information.
+			]],
+			Functions =
+			{
+				Trace = { Params = "{{cWorld}}, Callbacks, StartX, StartY, StartZ, EndX, EndY, EndZ", Return = "bool", Notes = "(STATIC) Performs the trace on the specified line. Returns true if the entire trace was processed (no callback returned true)" },
 			},
 			
+			AdditionalInfo =
+			{
+				{
+					Header = "Callbacks",
+					Contents = [[
+The Callbacks in the Trace() function is a table that contains named functions. MCServer will call
+individual functions from that table for the events that occur on the line - hitting a block, going out of
+valid world data etc. The following table lists all the available callbacks. If the callback function is
+not defined, MCServer skips it. Each function can return a bool value, if it returns true, the tracing is
+aborted and Trace() returns false.</p>
+<p>
+<table><tr><th>Name</th><th>Parameters</th><th>Notes</th></tr>
+<tr><td>OnNextBlock</td><td>BlockX, BlockY, BlockZ, BlockType, BlockMeta, EntryFace</td>
+	<td>Called when the ray hits a new valid block. The block type and meta is given. EntryFace is one of the
+	BLOCK_FACE_ constants indicating which "side" of the block got hit by the ray.</td></tr>
+<tr><td>OnNextBlockNoData</td><td>BlockX, BlockY, BlockZ, EntryFace</td>
+	<td>Called when the ray hits a new block, but the block is in an unloaded chunk - no valid data is
+	available. Only the coords and the entry face are given.</td></tr>
+<tr><td>OnOutOfWorld</td><td>X, Y, Z</td>
+	<td>Called when the ray goes outside of the world (Y-wise); the coords specify the exact exit point. Note
+	that for other paths than lines (considered for future implementations) the path may leave the world and
+	go back in again later, in such a case this callback is followed by OnIntoWorld() and further
+	OnNextBlock() calls.</td></tr>
+<tr><td>OnIntoWorld</td><td>X, Y, Z</td>
+	<td>Called when the ray enters the world (Y-wise); the coords specify the exact entry point.</td></tr>
+<tr><td>OnNoMoreHits</td><td>&nbsp;</td>
+	<td>Called when the path is sure not to hit any more blocks. This is the final callback, no more
+	callbacks are called after this function. Unlike the other callbacks, this function doesn't have a return
+	value.</td></tr>
+<tr><td>OnNoChunk</td><td>&nbsp;</td>
+	<td>Called when the ray enters a chunk that is not loaded. This usually means that the tracing is aborted.
+	Unlike the other callbacks, this function doesn't have a return value.</td></tr>
+</table>
+					]],
+				},
+				{
+					Header = "Example",
+					Contents = [[
+<p>The following example is taken from the Debuggers plugin. It is a command handler function for the
+"/spidey" command that creates a line of cobweb blocks from the player's eyes up to 50 blocks away in
+the direction they're looking, but only through the air.
+<pre>
+function HandleSpideyCmd(a_Split, a_Player)
+	local World = a_Player:GetWorld();
+
+	local Callbacks = {
+		OnNextBlock = function(a_BlockX, a_BlockY, a_BlockZ, a_BlockType, a_BlockMeta)
+			if (a_BlockType ~= E_BLOCK_AIR) then
+				-- abort the trace
+				return true;
+			end
+			World:SetBlock(a_BlockX, a_BlockY, a_BlockZ, E_BLOCK_COBWEB, 0);
+		end
+	};
+	
+	local EyePos = a_Player:GetEyePosition();
+	local LookVector = a_Player:GetLookVector();
+	LookVector:Normalize();  -- Make the vector 1 m long
+	
+	-- Start cca 2 blocks away from the eyes
+	local Start = EyePos + LookVector + LookVector;
+	local End = EyePos + LookVector * 50;
+	
+	cLineBlockTracer.Trace(World, Callbacks, Start.x, Start.y, Start.z, End.x, End.y, End.z);
+	
+	return true;
+end
+</pre>
+</p>
+					]],
+				},
+			},  -- AdditionalInfo
+		},  -- cLineBlockTracer
+		
 		cLuaWindow =
 		{
 			Desc = [[This class is used by plugins wishing to display a custom window to the player, unrelated to block entities or entities near the player. The window can be of any type and have any contents that the plugin defines. Callbacks for when the player modifies the window contents and when the player closes the window can be set.