From a7401fa8329be3c9b33935ebffd1088f9e6088e4 Mon Sep 17 00:00:00 2001 From: madmaxoft 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/Plugins/APIDump') 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.

+

+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.

+

+ + + + + + + + + + + + + +
NameParametersNotes
OnNextBlockBlockX, BlockY, BlockZ, BlockType, BlockMeta, EntryFaceCalled 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.
OnNextBlockNoDataBlockX, BlockY, BlockZ, EntryFaceCalled 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.
OnOutOfWorldX, Y, ZCalled 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.
OnIntoWorldX, Y, ZCalled when the ray enters the world (Y-wise); the coords specify the exact entry point.
OnNoMoreHits 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.
OnNoChunk 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.
+ ]], + }, + { + Header = "Example", + Contents = [[ +

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. +

+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
+
+

+ ]], + }, + }, -- AdditionalInfo + }, -- cLineBlockTracer cLuaWindow = { -- cgit v1.2.3