3 files changed, 189 insertions, 32 deletions

diff --git a/Server/Plugins/APIDump/Classes/Geometry.lua b/Server/Plugins/APIDump/Classes/Geometry.lua
index cd7793ee9..32a4bbb27 100644
--- a/Server/Plugins/APIDump/Classes/Geometry.lua
+++ b/Server/Plugins/APIDump/Classes/Geometry.lua
@@ -977,52 +977,103 @@ return
 	{
 		Desc = [[
 This class provides an easy-to-use interface for 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 static 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.
+blocks in the world. It can either be used to call the provided callbacks according
+to what events it encounters along the way, or there are shortcut functions used for
+the most popular tracing reasons - line of sight and solid hits.
 		]],
 		Functions =
 		{
-			Trace =
+			FirstSolidHitTrace =
 			{
-				IsStatic = true,
-				Params =
 				{
+					IsStatic = true,
+					Params =
 					{
-						Name = "World",
-						Type = "cWorld",
+						{ Name = "World",  Type = "cWorld" },
+						{ Name = "StartX", Type = "number" },
+						{ Name = "StartY", Type = "number" },
+						{ Name = "StartZ", Type = "number" },
+						{ Name = "EndX",   Type = "number" },
+						{ Name = "EndY",   Type = "number" },
+						{ Name = "EndZ",   Type = "number" },
 					},
+					Returns =
 					{
-						Name = "Callbacks",
-						Type = "table",
+						{ Name = "HasHitSolid",    Type = "boolean" },
+						{ Name = "HitCoords",      Type = "Vector3d" },
+						{ Name = "HitBlockCoords", Type = "Vector3i" },
+						{ Name = "HitBlockFace",   Type = "eBlockFace" },
 					},
+					Notes = "If the specified line hits a solid block, return true and the coordinates / face of the first such solid block hit. Returns false if there's no solid block on that line.",
+				},
+				{
+					IsStatic = true,
+					Params =
 					{
-						Name = "StartX",
-						Type = "number",
+						{ Name = "World", Type = "cWorld" },
+						{ Name = "Start", Type = "Vector3d" },
+						{ Name = "End",   Type = "Vector3d" },
 					},
+					Returns =
 					{
-						Name = "StartY",
-						Type = "number",
+						{ Name = "HasHitSolid",    Type = "boolean" },
+						{ Name = "HitCoords",      Type = "Vector3d" },
+						{ Name = "HitBlockCoords", Type = "Vector3i" },
+						{ Name = "HitBlockFace",   Type = "eBlockFace" },
 					},
+					Notes = "If the specified line hits a solid block, return true and the coordinates / face of the first such solid block hit. Returns false if there's no solid block on that line.",
+				},
+			},  -- FirstSolidHitTrace
+			LineOfSightTrace =
+			{
+				{
+					IsStatic = true,
+					Params =
 					{
-						Name = "StartZ",
-						Type = "number",
+						{ Name = "World",  Type = "cWorld" },
+						{ Name = "StartX", Type = "number" },
+						{ Name = "StartY", Type = "number" },
+						{ Name = "StartZ", Type = "number" },
+						{ Name = "EndX",   Type = "number" },
+						{ Name = "EndY",   Type = "number" },
+						{ Name = "EndZ",   Type = "number" },
+						{ Name = "Sight",  Type = "number" },
 					},
+					Returns =
 					{
-						Name = "EndX",
-						Type = "number",
+						{ Name = "CanSee", Type = "boolean" },
 					},
+					Notes = "Returns true if the two points specified are within line of sight of each other. The Sight parameter specifies which blocks are considered transparent for the trace, it is a combination of {{cLineBlockTracer#eLineOfSight|losXXX}} values added together."
+				},
+				{
+					IsStatic = true,
+					Params =
 					{
-						Name = "EndY",
-						Type = "number",
+						{ Name = "World", Type = "cWorld" },
+						{ Name = "Start", Type = "Vector3d" },
+						{ Name = "End",   Type = "Vector3d" },
+						{ Name = "Sight", Type = "number" },
 					},
+					Returns =
 					{
-						Name = "EndZ",
-						Type = "number",
+						{ Name = "CanSee", Type = "boolean" },
 					},
+					Notes = "Returns true if the two points specified are within line of sight of each other. The Sight parameter specifies which blocks are considered transparent for the trace, it is a combination of {{cLineBlockTracer#eLineOfSight|losXXX}} values added together."
+				},
+			},  -- LineOfSightTrace
+			Trace =
+			{
+				IsStatic = true,
+				Params =
+				{
+					{ Name = "World",     Type = "cWorld" },
+					{ Name = "Callbacks", Type = "table" },
+					{ Name = "StartX",    Type = "number" },
+					{ Name = "StartY",    Type = "number" },
+					{ Name = "StartZ",    Type = "number" },
+					{ Name = "EndX",      Type = "number" },
+					{ Name = "EndY",      Type = "number" },
+					{ Name = "EndZ",      Type = "number" },
 				},
 				Returns =
 				{
@@ -1033,6 +1084,29 @@ various events. See below for further information.
 				Notes = "Performs the trace on the specified line. Returns true if the entire trace was processed (no callback returned true)",
 			},
 		},
+		Constants =
+		{
+			losAir =
+			{
+				Notes = "LineOfSight tracing can 'see' through air blocks.",
+			},
+			losWater =
+			{
+				Notes = "LineOfSight tracing can 'see' through water blocks.",
+			},
+			losLava =
+			{
+				Notes = "LineOfSight tracing can 'see' through lava blocks.",
+			},
+		},
+		ConstantGroups =
+		{
+			eLineOfSight =
+			{
+				Include = "los.*",
+				TextBefore = "The following constants are used to speficy which blocks are see-through when tracing a LineOfSight trace. Add them together to make up the Sight parameter.",
+			},
+		},
 		AdditionalInfo =
 		{
 			{
@@ -1109,16 +1183,15 @@ end
 	cTracer =
 	{
 		Desc = [[
-			A cTracer object is used to trace lines in the world. One thing you can use the cTracer for, is
-			tracing what block a player is looking at, but you can do more with it if you want.</p>
-			<p>
-			The cTracer is still a work in progress and is not documented at all.</p>
-			<p>
-			See also the {{cLineBlockTracer}} class for an alternative approach using callbacks.
+			This class is <b>OBSOLETE</b>, do not use it.
+			See the {{cLineBlockTracer}} class for the replacement.
 		]],
 		Functions =
 		{
-
+			Trace =
+			{
+				Notes = "<b>OBSOLETE</b>, use the {{cLineBlockTracer}} class instead.",
+			},
 		},
 	},
 	Vector3d =
diff --git a/Server/Plugins/Debuggers/Debuggers.lua b/Server/Plugins/Debuggers/Debuggers.lua
index 7d7246484..fb18a0c19 100644
--- a/Server/Plugins/Debuggers/Debuggers.lua
+++ b/Server/Plugins/Debuggers/Debuggers.lua
@@ -1838,6 +1838,44 @@ end
 
 
 
+function HandleConsoleHitTrace(a_Split)
+	local world = cRoot:Get():GetDefaultWorld()
+	local s = Vector3d(0, 70, 0)
+	local e = Vector3d(100, 75, 100)
+	if (tonumber(a_Split[2])) then
+		s.x = tonumber(a_Split[2])
+	end
+	if (tonumber(a_Split[3])) then
+		s.y = tonumber(a_Split[3])
+	end
+	if (tonumber(a_Split[4])) then
+		s.z = tonumber(a_Split[4])
+	end
+	if (tonumber(a_Split[5])) then
+		e.x = tonumber(a_Split[5])
+	end
+	if (tonumber(a_Split[6])) then
+		e.y = tonumber(a_Split[6])
+	end
+	if (tonumber(a_Split[7])) then
+		e.z = tonumber(a_Split[7])
+	end
+	local res, hitCoords, hitBlockCoords, hitBlockFace = cLineBlockTracer:FirstSolidHitTrace(world, s, e)
+	if (res) then
+		return true, string.format("The line hits block {%d, %d, %d} at point {%f, %f, %f}, face %s",
+			hitBlockCoords.x, hitBlockCoords.y, hitBlockCoords.z,
+			hitCoords.x, hitCoords.y, hitCoords.z,
+			BlockFaceToString(hitBlockFace)
+		)
+	else
+		return true, "The two points specified don't have a solid block between them."
+	end
+end
+
+
+
+
+
 --- Monitors the state of the "inh" entity-spawning hook
 -- if false, the hook is installed before the "inh" command processing
 local isInhHookInstalled = false
@@ -1954,6 +1992,40 @@ end
 
 
 
+function HandleConsoleLosTrace(a_Split)
+	local world = cRoot:Get():GetDefaultWorld()
+	local s = Vector3d(0, 70, 0)
+	local e = Vector3d(100, 75, 100)
+	if (tonumber(a_Split[2])) then
+		s.x = tonumber(a_Split[2])
+	end
+	if (tonumber(a_Split[3])) then
+		s.y = tonumber(a_Split[3])
+	end
+	if (tonumber(a_Split[4])) then
+		s.z = tonumber(a_Split[4])
+	end
+	if (tonumber(a_Split[5])) then
+		e.x = tonumber(a_Split[5])
+	end
+	if (tonumber(a_Split[6])) then
+		e.y = tonumber(a_Split[6])
+	end
+	if (tonumber(a_Split[7])) then
+		e.z = tonumber(a_Split[7])
+	end
+	local res = cLineBlockTracer:LineOfSightTrace(world, s, e, cLineBlockTracer.losAir)
+	if (res) then
+		return true, "The two points can see each other."
+	else
+		return true, "The two points cannot see each other"
+	end
+end
+
+
+
+
+
 function HandleConsolePluginStats(a_Split)
 	cPluginManager:ForEachPlugin(
 		function (a_CBPlugin)
diff --git a/Server/Plugins/Debuggers/Info.lua b/Server/Plugins/Debuggers/Info.lua
index 8b2e7017b..dea656837 100644
--- a/Server/Plugins/Debuggers/Info.lua
+++ b/Server/Plugins/Debuggers/Info.lua
@@ -290,6 +290,12 @@ g_PluginInfo =
 			HelpString = "Tests the crypto hashing functions",
 		},
 
+		["hittrace"] =
+		{
+			Handler = HandleConsoleHitTrace,
+			HelpString = "Tests the FirstSolidHit trace",
+		},
+
 		["inh"] =
 		{
 			Handler = HandleConsoleInh,
@@ -302,6 +308,12 @@ g_PluginInfo =
 			HelpString = "Loads the specified chunk into memory",
 		},
 
+		["lostrace"] =
+		{
+			Handler = HandleConsoleLosTrace,
+			HelpString = "Tests a LineOfSight trace",
+		},
+
 		["pluginstats"] =
 		{
 			Handler = HandleConsolePluginStats,