Merge branch 'master' of https://github.com/ShadowNinja/areas

Merge ShadowNinja's version

api.lua

@@ -1,22 +1,17 @@
-local protection_detectors = {}
+local hudHandlers = {}
 
--- Other protection mods should be able to display their protection in the hud
-areas.registerHudHandler = function(handler)
-	protection_detectors[#protection_detectors + 1] = handler
+--- Adds a function as a HUD handler, it will be able to add items to the Areas HUD element.
+function areas:registerHudHandler(handler)
+	table.insert(hudHandlers, handler)
 end
 
--- Generalized call to registered handlers to add their proeciton labels to the areas list
-function areas:getRegisteredProtections(pos)
-	local area_list = {}
-	if #protection_detectors <= 0 then
-		return area_list
-	end
 
-	for idx=1, #protection_detectors do
-		local func = protection_detectors[idx]
-		area_list = func(pos, area_list)
+function areas:getExternalHudEntries(pos)
+	local areas = {}
+	for _, func in pairs(hudHandlers) do
+		func(pos, areas)
 	end
-	return area_list
+	return areas
 end
 
 --- Returns a list of areas that include the provided position.

api.md

@@ -44,3 +44,49 @@ Example
 	end
 
 	areas.register_hud_handler(myhandler)
+=======
+Areas mod API
+===
+
+API list
+---
+
+ * `areas.registerHudHandler(handler)` - Registers a handler to add items to the Areas HUD.  See [HUD](#hud).
+
+
+HUD
+---
+
+If you are making a protection mod or a similar mod that adds invisible regions
+to the world, and you would like then to show up in the areas HUD element, you
+can register a callback to show your areas.
+
+HUD handler specification:
+
+ * `handler(pos, list)`
+   * `pos` - The position to check.
+   * `list` - The list of area HUD elements, this should be modified in-place.
+
+The area list item is a table containing a list of tables with the following fields:
+
+ * `id` - An identifier for the area. This should be a unique string in the format `mod:id`.
+ * `name` - The name of the area.
+ * `owner` - The player name of the region owner, if any.
+
+All of the fields are optional but at least one of them must be set.
+
+### Example
+
+	local function areas_hud_handler(pos, areas)
+		local val = find_my_protection(pos)
+
+		if val then
+			table.insert(areas, {
+				id = "mod:"..val.id,
+				name = val.name,
+				owner = val.owner,
+			})
+		end
+	end
+
+	areas:registerHudHandler(areas_hud_handler)

hud.lua

@@ -14,15 +14,12 @@ minetest.register_globalstep(function(dtime)
 					area.open and ":open" or ""))
 		end
 
-		for id, area in pairs(areas:getRegisteredProtections(pos)) do
-			table.insert(
-				areaStrings, ("%s [%s] (%s)")
-				:format(
-					area.name or "",
-					id ,
-					area.owner
-				)
-			)
+		for i, area in pairs(areas:getExternalHudEntries(pos)) do
+			local str = ""
+			if area.name then str = area.name .. " " end
+			if area.id then str = str.."["..area.id.."] " end
+			if area.owner then str = str.."("..area.owner..")" end
+			table.insert(areaStrings, str)
 		end
 
 		local areaString = "Areas:"