summaryrefslogtreecommitdiffstats
path: root/MCServer/Plugins/APIDump
diff options
context:
space:
mode:
Diffstat (limited to 'MCServer/Plugins/APIDump')
-rw-r--r--MCServer/Plugins/APIDump/APIDesc.lua90
1 files changed, 86 insertions, 4 deletions
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 =
{