Add support for statbar “off state” icons

[Wuzzy2]

Closes #6030.

This adds support for optional “off state” icons for statbars. “off state icons” can be used to denote the lack of something, like missing hearts or bubbles.

Implementation

This implementation is 100% network-compatible.

The “off state” image is set by using the text field of the HUD definition. To add the “off state” image, append a slash to the original texture name, then the additional texture name to the text field of the HUD definition. Example: heart.png/heart_gone.png. Here, heart.png is the normal icon, and heart_gone.png is the “off state”. If no slash is found, the background image is disabled.

The “maximum value” is set by using the item field.

For the builtin health bar and breath bar, health_gone.png and breath_gone.png are used, respectively. Note the default images are empty, so games need to add these images first.

Implementation rationale and details

The slash was chosen as this is character is forbidden in most OSes.

I would have loved to provide non-empty default _gone images, but decided aginst that because adding visible images would break compability of existing games. Existing games don't have those images yet and add default images would not fit well together with the game-provided heart.png/bubble.png.

Technically, the “off state” does not act as a background of the normal image. Instead, the “off state” icons replace the normal icons. I decided against using overlays because it would have made drawing semitransparent icons (like bubbles) quite annoying.

To do

This PR is ready for review.

How to test

Use this test mod and use the /statbar command to generate a random statbar (random image count and direction):

local bar = nil

minetest.register_chatcommand("statbar", {
	privs = {},
	description = "Render test statbar",
	params = "[<textures>] | clear",
	func = function(name, param)
		local player = minetest.get_player_by_name(name)
		if not player then
			return false, "No player"
		end
		if bar then
			player:hud_remove(bar)
			bar = nil
		end
		if param == "clear" then
			return true
		end
		if param == "" then
			param = "heart.png/heart_gone.png"
		end
		local dir = math.random(0,3)
		local max = math.random(1,15)
		local num = math.random(0,max)
		minetest.chat_send_player(name, "direction="..dir.."; value="..num.."/"..max)
		bar = player:hud_add({
			hud_elem_type = "statbar",
			number = num,
			item = max,
			size = { x = 24, y = 24 },
			position = { x = 0.5, y = 0.5 },
			offset = { x = - 12, y = -12 },
			text = param,
			direction = dir,
		})
		return true
	end,
})

Additionally, you want to test the behavior or the builtin health and breath statbars. You need to replace heart_gone.png and bubble_gone.png for testing purposes because the default ones are empty/transparent.

[MoNTE48]

Server 5.2, client 5.0. The client will see only "on state", the behavior will not change?

[Wuzzy2]

@sfan5: OK, I introduced a new field text2 for the 2nd texture name.

@MoNTE48: The alt. texture will not appear by default. Read the whole 1st post again.

[Wuzzy2]

@sfan5: Done.

[Wuzzy2]

Done, rebased and squashed!

[sfan5]

textures/base/pack/heart.png:      PNG image data, 12 x 12, 4-bit colormap, non-interlaced

textures/base/pack/heart_gone.png: PNG image data, 12 x 12, 4-bit colormap, non-interlaced

uh? solved, user error

[Wuzzy2]

Weird about the heart thing. Also tested in Minimal with game-provided heart.png removed. Still not reproducible. Note that heart.png and bubble.png are not even touched in this PR.

[Wuzzy2]

Note that MTG uses the wrong size for both heart.png and bubble.png (16×16 instead of 12×12).

[sfan5]

Works.

[SmallJoker]

@Wuzzy2 Would you please be so nice and rebase this PR?

[Wuzzy2]

This is ready now!

[SmallJoker]

Code looks better now. PR works.

Two suggestions in the documentation - what do you think about those?

[Wuzzy2]

Looks good.

[ClobberXD]

The new item field is somewhat non-descriptive, IMHO. If it denotes the maximum value, why not call it max?

[SmallJoker]

@sfan5 Outdated review. Does the PR need any change, or does it still look good?

[sfan5]

Still looks good, you can fix the comment before merge if you want.