Allow to change HUD bar images and label later

API.md

@@ -99,22 +99,39 @@ Always `nil`.
 
 
 ## Modifying a HUD bar
-After a HUD bar has been added, you can change the current and maximum value on a per-player basis.
+After a HUD bar has been added, you can change the current and maximum value and other attributes on a per-player basis.
 You use the function `hb.change_hudbar` for this.
 
-### `hb.change_hudbar(player, identifier, new_value, new_max_value)`
+### `hb.change_hudbar(player, identifier, new_value, new_max_value, new_icon, new_bgicon, new_bar, new_label, new_text_color)`
-Changes the values of an initialized HUD bar for a certain player. `new_value` and `new_max_value`
+Changes the values and the appearance of an initialized HUD bar for a certain player. `new_value`
-can be `nil`; if one of them is `nil`, that means the value is unchanged. If both values
+and `new_max_value` are the most important parameters as they specify the new current and maximum new values, you do not need
-are `nil`, this function is a no-op.
+to worry too much about the other parameters.
-This function also tries minimize the amount of calls to `hud_change` of the Minetest Lua API, and
+
-therefore, network traffic. `hud_change` is only called if it is actually needed, i.e. when the
+The following parameters are less important and provided for styling the HUD bar after registration (if
-actual length of the bar or the displayed string changed, so you do not have to worry about it.
+this is desired). The “styling” parameters parallel the parameters of `hb.register_hudbar`. It is
+recommended to not change the style of a HUD bar too often as this can be distracting or confusing
+for players.
+
+`new_value`, `new_max_value` `new_icon`, `new_bgicon`, `new_bar`, `new_label` and `new_text_color` can be
+`nil`; if one of them is `nil`, that means the value is unchanged. If all those values are `nil`, this
+function is a no-op.
+
+This function tries to minimize the amount of calls to `hud_change` of the Minetest Lua API
+(and thus, network traffic), when you only change the value and/or  maximum value. In this case,
+`hud_change` is only called if it is actually needed, e.g. when the actual length of the bar
+or the displayed string changed, so you do not have to worry about it. There is, however, no
+such network optimization for the “styling” parameters, so keep this in mind.
 
 #### Parameters
 * `player`: `ObjectRef` of the player to which the HUD bar belongs to
 * `identifier`: The identifier of the HUD bar type to change, as specified in `hb.register_hudbar`.
 * `new_value`: The new current value of the HUD bar
 * `new_max_value`: The new maximum value of the HUD bar
+* `new_icon`: File name of the new icon
+* `new_bgicon`: File name of the new background icon for the modern-style statbar
+* `new_bar`: File name of the new bar segment image
+* `new_label`: A new text label of the HUD bar. Note the format string still applies
+* `new_text_color`: A 3-octet number defining the new color of the text.
 
 #### Return value
 Always `nil`.

init.lua

@@ -281,7 +281,7 @@ function hb.init_hudbar(player, identifier, start_value, start_max, start_hidden
 	hb.hudtables[identifier].add_all(player, hudtable, start_value, start_max, start_hidden)
 end
 
-function hb.change_hudbar(player, identifier, new_value, new_max_value)
+function hb.change_hudbar(player, identifier, new_value, new_max_value, new_icon, new_bgicon, new_bar, new_label, new_text_color)
 	if new_value == nil and new_max_value == nil then
 		return
 	end
@@ -307,6 +307,33 @@ function hb.change_hudbar(player, identifier, new_value, new_max_value)
 		new_max_value = hudtable.hudstate[name].max
 	end
 
+	if hb.settings.bar_type == "progress_bar" then
+		if new_icon ~= nil and hudtable.hudids[name].icon ~= nil then
+			player:hud_change(hudtable.hudids[name].icon, "text", new_icon)
+		end
+		if new_bgicon ~= nil and hudtable.hudids[name].bgicon ~= nil then
+			player:hud_change(hudtable.hudids[name].bgicon, "text", new_bgicon)
+		end
+		if new_bar ~= nil then
+			player:hud_change(hudtable.hudids[name].bar , "text", new_bar)
+		end
+		if new_label ~= nil then
+			hudtable.label = new_label
+			local new_text = string.format(hudtable.format_string, new_label, hudtable.hudstate[name].value, hudtable.hudstate[name].max)
+			player:hud_change(hudtable.hudids[name].text, "text", new_text)
+		end
+		if new_text_color ~= nil then
+			player:hud_change(hudtable.hudids[name].text, "number", new_text_color)
+		end
+	else
+		if new_icon ~= nil and hudtable.hudids[name].bar ~= nil then
+			player:hud_change(hudtable.hudids[name].bar, "text", new_icon)
+		end
+		if new_bgicon ~= nil and hudtable.hudids[name].bg ~= nil then
+			player:hud_change(hudtable.hudids[name].bg, "text", new_bgicon)
+		end
+	end
+
 	local main_error_text =
 		"[hudbars] Bad call to hb.change_hudbar, identifier: “"..tostring(identifier).."”, player name: “"..name.."”. "
 	if new_max_value < new_value then