Add new function: hb.get_hudbar_state

API.md

@@ -152,3 +152,23 @@ Makes a previously hidden HUD bar visible again to a player.
 #### Return value
 Always `nil`.
 
+
+## Reading HUD bar information
+It is also possible to read information about an active HUD bar.
+
+### `hb.get_hudbar_state(player, identifier)`
+Returns the current state of the active player's HUD bar.
+
+#### Parameters
+* `player`: `ObjectRef` of the player to which the HUD bar belongs to
+* `identifier`: The identifier of the HUD bar type to hide, as specified in `hb.register_hudbar`.
+
+#### Return value
+A table which holds information on the current state of the HUD bar. Note the table is a partial
+copy of the internal HUD bar state, it is *not* a reference; the information hold by the table is
+only true for the moment you called this function. The fields of this table are:
+* `value`: Current value of HUD bar
+* `max`: Current maximum value of HUD bar
+* `hidden`: Boolean denoting whether the HUD bar is hidden
+* `barlength`: The length of the HUD bar in pixels. This field is meaningless if the HUD bar is currently hidden.
+* `text`: The text shown on the HUD bar. This fiels is meaningless if the HUD bar is currently hidden.

init.lua

@@ -105,6 +105,7 @@ function hb.register_hudbar(identifier, text_color, label, textures, default_sta
 			direction = 0,
 			offset = { x = offset.x + 2,  y = offset.y },
 		})
+		-- Do not forget to update hb.get_hudbar_state if you add new fields to the state table
 		state.hidden = start_hidden
 		state.value = start_value
 		state.max = start_max
@@ -214,6 +215,19 @@ function hb.unhide_hudbar(player, identifier)
 	end
 end
 
+function hb.get_hudbar_state(player, identifier)
+	local ref = hb.get_hudtable(identifier).hudstate[player:get_player_name()]
+	-- Do not forget to update this chunk of code in case the state changes
+	local copy = {
+		hidden = ref.hidden,
+		value = ref.value,
+		max = ref.max,
+		text = ref.text,
+		barlength = ref.barlength,
+	}
+	return copy
+end
+
 --register built-in HUD bars
 hb.register_hudbar("health", 0xFFFFFF, "Health", { bar = "hudbars_bar_health.png", icon = "hudbars_icon_health.png" }, 20, 20, false)
 hb.register_hudbar("breath", 0xFFFFFF, "Breath", { bar = "hudbars_bar_breath.png", icon = "hudbars_icon_breath.png" }, 10, 10, true)