--------------------------------------------------------------------------------
--
--   Utility Functions
--
--------------------------------------------------------------------------------

--? @group World
--? @shortdesc Find a position on a path hidden from view, as close to the destination as possible whilst still satisfying your hidden checktype. Checktype can be either CHECK_IN_FOW, CHECK_OFFCAMERA or CHECK_BOTH.
--? @extdesc The path is always calculated as if it were plain infantry. This function returns nil if it can't find a suitable position, so you can do a backup plan. 
--? @result Position
--? @args PlayerID player, MarkerID/Pos origin, MarkerID/Pos destination, Integer checktype
function World_GetHiddenPositionOnPath(playerid, origin, dest, checktype)

	if scartype(origin) == ST_MARKER then
		origin = Marker_GetPosition(origin)
	end
	if scartype(dest) == ST_MARKER then
		dest = Marker_GetPosition(dest)
	end

	local eid = Util_GetEntityBlueprintID("ebps/races/allies/soldiers/infantry_rifleman.lua")
	local pos = Misc_GetHiddenPositionOnPath(checktype, dest, origin, eid, 10, 10, playerid, false)

	if (pos.x == 0) and (pos.y == 0) and (pos.x == 0) then
		return nil
	else
		return pos
	end

end

--? @group Marker
--? @shortdesc Returns a random position within the marker's proximity. Range is ignored for rectangular markers
--? @result Pos
--? @args MarkerID/Pos marker[, Real range]
function Marker_GetRandomPosition(marker, range)

	local pos
	
	if scartype(marker) == ST_MARKER then
		
		if range == nil or scartype(range) ~= ST_NUMBER then
			if Marker_GetProximityType(marker) == PT_Rectangle then
				range = 0 -- range doesn't apply to rectangular markers, but make it an int anyway so the function call below works
			else
				range = Marker_GetProximityRadius(marker)
			end
			
		end
		
		return Marker_GetRandomPositionInternal(marker, range)
		
	elseif scartype(marker) == ST_SCARPOS then
		
		pos = marker
		if range == nil then
			range = 0
		end
		
		local dir = World_GetRand(1, math.floor(2000*math.pi)) / 1000
		local offset = World_GetRand(1, (range * 1000)) / 1000
		
		return World_Pos(pos.x + (math.cos(dir) * offset), pos.y, pos.z + (math.sin(dir) * offset))
		
	end
	
end

--? @group Marker
--? @shortdesc Builds a table of MarkerIDs that are named in a sequence. i.e. a name of "spot" will find markers "spot1", "spot2" and so on, up until it looks for a marker that isn't there.
--? @args String name
--? @result Table
function Marker_GetSequence(name)

	local num = 1
	local result = {}
	
	while Marker_Exists(name..num, "basic_marker") do
		table.insert(result, Marker_FromName(name..num, "basic_marker"))
		num = num + 1
	end
	
	if num >= 2 then
		print("Retrieved sequence of Markers: "..name.."1 to "..name..(num-1))
	end
	
	return result
	
end
