From a7401fa8329be3c9b33935ebffd1088f9e6088e4 Mon Sep 17 00:00:00 2001
From: madmaxoft <github@xoft.cz>
Date: Fri, 4 Oct 2013 21:53:14 +0200
Subject: APIDump: Added cLineBlockTracer documentation.

---
 MCServer/Plugins/APIDump/APIDesc.lua | 90 ++++++++++++++++++++++++++++++++++--
 1 file changed, 86 insertions(+), 4 deletions(-)

(limited to 'MCServer')

diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua
index 5779e18bc..c849e0e3d 100644
--- a/MCServer/Plugins/APIDump/APIDesc.lua
+++ b/MCServer/Plugins/APIDump/APIDesc.lua
@@ -1168,10 +1168,92 @@ 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 =
 		{
-- 
cgit v1.2.3