Find historical figure in Dwarf Fortress using DFhack

findHF.lua

-- Locates a historical figure (HF) on the world map. 
-- Pass any part of the unit's (translated or native) name as an argument to the script.
-- The script will print out the current location of the historical figure, whatever it is traveling the world, or inside a site

local function matchName(searchName, nameObj)
	translated = dfhack.TranslateName(nameObj, true)
	notTranslated = dfhack.TranslateName(nameObj, false)
	searchName = string.lower(searchName)
	if string.match(string.lower(translated), searchName) then
		return translated
	end

	if string.match(string.lower(notTranslated), searchName) then
		return notTranslated
	end
	return false
end

local function getHFbyNameLocally(searchName)
	for _,unit in ipairs(df.global.world.units.all) do
		res = matchName(searchName, unit.name)
		if res then
			return {true, res, unit.pos}
		end
	end
	return false
end

local function getHFnemesisFromName(searchName)
	for id, hf in pairs(df.global.world.history.figures) do
		name = matchName(searchName, hf.name)
		if name then
			return {true, name, hf.unit_id, hf.site_links}
		end
	end
	return false
end

local function getAdvPosWorldMap()
	for id, adv in pairs(df.global.world.armies.all) do
		if adv.flags[0] == true then
			return {true, adv.pos}
		end
	end
	return false
end

local function getHFPosWorldMapArmy(nemesis_id)
	for _, army in ipairs(df.global.world.armies.all) do
		for _, member in ipairs(army.members) do
			if member.nemesis_id == tonumber(nemesis_id) then
				return {true, army.pos}
			end
		end
	end
	return false
end

local function getSiteInfoFromId(id)
	for _, site in ipairs(df.global.world.world_data.sites) do
		if site.id == tonumber(id) then
			return {true, dfhack.TranslateName(site.name, true), site.pos}
		end
	end
	return false
end	

local function getHFPosWorldMapSite(nemesis_id)
	for _, site in ipairs(df.global.world.world_data.sites) do
		for _, nem in ipairs(site.unk_1.nemesis) do
			if nem == tonumber(nemesis_id) then
				return {true, dfhack.TranslateName(site.name, true), site.pos}
			end
		end
	end
	return false
end

local function printAdvWorldPos()
	advPos = getAdvPosWorldMap()
	if (advPos) then
		print("------------------------------------")
		print("Your world pos:\t", pos2xy(advPos[2]))
		print("Your region pos:", math.floor(advPos[2].x / 48), math.floor(advPos[2].y / 48))
	else
		print("------------------------------------")
		print("Your region pos:", df.global.world.world_data.adv_region_x, df.global.world.world_data.adv_region_y)
	end
end

--------------------------------------------------------------

local arg = ...
if not arg then
	error("Please enter a Historical Figure (HF) name as argument")
end

print("Searching for HF named:", arg)

HFPos = getHFbyNameLocally(arg)
if HFPos then
	print("Found HF named: ", dfhack.df2console(HFPos[2]))
	print("------------------------------------")
	print("Found HF in the same site as you")
	print("HF local position:\t", HFPos[3].x, HFPos[3].y, HFPos[3].z)
	advPos = df.global.world.units.active[0].pos
	print("Your local position:\t", advPos.x, advPos.y, advPos.z)
	return 0
end

hf = getHFnemesisFromName(arg)
if (hf == false) then
	error("Couldn't find a HF with that name")
end

print("Found HF named: ", dfhack.df2console(hf[2]))
print("------------------------------------")

HFPos = getHFPosWorldMapArmy(hf[3])
if HFPos then
	print("Found HF traveling the world")
	print("HF world pos:\t", pos2xy(HFPos[2]))
	print("HF region pos:\t", math.floor(HFPos[2].x / 48), math.floor(HFPos[2].y / 48))
	printAdvWorldPos()
	return 0
end

HFPos = getHFPosWorldMapSite(hf[3])
if HFPos then
	print("Found HF in a site")
	print("Site name:\t", dfhack.df2console(HFPos[2]))
	print("Site region pos:", pos2xy(HFPos[3]))
	printAdvWorldPos()
	return 0
end

siteCount = 0
for Index, site in pairs( hf[4] ) do
	siteInfo = getSiteInfoFromId(hf[4][0].site)
	if siteInfo then
		print("The HF can *probably* be found if you look in this site(s)")
		print("Site name:\t", dfhack.df2console(siteInfo[2]))
		print("Site region pos:", pos2xy(siteInfo[3]))
		siteCount = siteCount + 1
	end
end

if siteCount == 0 then
	error("The HF couldn't be found in this world!")
end